mux/DOCS.md

Mux Documentation Index

Welcome to the Mux documentation! This page helps you navigate all available documentation.

📚 Documentation Files

Getting Started

• QUICKSTART.md - Get up and running in 5 minutes
  • Installation instructions
  • Your first route
  • Common patterns
  • Complete working example
  • Testing examples
  • Troubleshooting

Main Documentation

• README.md - Comprehensive project documentation
  • Full API reference
  • Detailed examples
  • Feature overview
  • Performance guidelines
  • Testing strategies
  • Complete working examples

Contributing

• CONTRIBUTING.md - Contribution guidelines
  • Code quality standards
  • Development workflow
  • Testing requirements
  • Commit conventions
  • Performance considerations
  • Documentation standards

Project Information

• CHANGELOG.md - Version history and changes

  • Release notes
  • Breaking changes
  • New features
  • Bug fixes
  • Migration guides

• SUMMARY.md - Recent changes summary

  • Latest improvements
  • API changes
  • Migration guide
  • Quality metrics

🚀 Quick Links by Topic

For New Users

1. Start with QUICKSTART.md
2. Read the "Basic Usage" section in README.md
3. Check out the example directory
4. Review common patterns in QUICKSTART.md

For API Reference

• Routing: README.md#basic-routing
• Middleware: README.md#middleware
• Groups: README.md#route-groups
• Resources: README.md#restful-resources
• Parameters: README.md#url-parameters
• Shutdown: README.md#graceful-shutdown

For Contributors

1. Read CONTRIBUTING.md thoroughly
2. Review code quality standards
3. Install development tools: make install-tools
4. Run quality checks: make check or ./check.sh
5. Follow the development workflow

For Migration

• Check CHANGELOG.md for breaking changes
• Review SUMMARY.md#migration-guide
• See API changes in SUMMARY.md#api-changes

📖 Code Examples

Live Examples

• example/main.go - Full working application
  • Complete server setup
  • Middleware examples
  • Resource routing
  • Group routing
  • Custom routes

Documentation Examples

• QUICKSTART.md - Simple, focused examples
• README.md - Comprehensive examples with explanations

🛠️ Development Tools

Makefile Commands

make help              # Show all available commands
make test              # Run tests
make check             # Run all quality checks
make install-tools     # Install dev tools
make run-example       # Run example server

Full list in Makefile

Quality Check Script

./check.sh            # Run all quality checks with colored output

Script details in check.sh

🔍 Configuration Files

Project Configuration

• .cursorrules - AI coding assistant rules
• .golangci.yml - Linting configuration
• Makefile - Development commands
• go.mod - Go module definition (Go 1.25+)

CI/CD

• .github/workflows/ci.yml - GitHub Actions workflow
  • Automated testing
  • Quality checks
  • Build verification

📋 API Overview

Core Components

Mux

The main router instance.

m := mux.New()
m.GET("/path", handler)
m.POST("/path", handler)
m.Use(middleware)
m.Group(func(grp *mux.Mux) { ... })
m.Resource("/pattern", func(res *mux.Resource) { ... })

Resource

RESTful resource routing.

// Standard routes
res.Index(handler)        // GET /pattern
res.Create(handler)       // POST /pattern
res.View(handler)         // GET /pattern/{id}
res.Update(handler)       // PUT /pattern/{id}
res.Delete(handler)       // DELETE /pattern/{id}

// Collection routes
res.GET("/search", handler)     // GET /pattern/search
res.POST("/bulk", handler)      // POST /pattern/bulk

// Member routes
res.MemberGET("/stats", handler)    // GET /pattern/{id}/stats
res.MemberPOST("/publish", handler) // POST /pattern/{id}/publish

Middleware

Standard signature: func(http.Handler) http.Handler

func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Before
        next.ServeHTTP(w, r)
        // After
    })
}

📊 Quality Standards

Required Checks

• ✅ go vet ./...
• ✅ staticcheck ./...
• ✅ fieldalignment ./...
• ✅ go test -race ./...

Running Checks

make check         # Run all checks
./check.sh         # Run with colored output

Details in CONTRIBUTING.md#code-quality-standards

🎯 Features

• ✅ HTTP method routing (GET, POST, PUT, DELETE, PATCH, etc.)
• ✅ Middleware support
• ✅ Route grouping
• ✅ RESTful resources
• ✅ URL parameters
• ✅ Graceful shutdown
• ✅ Zero dependencies
• ✅ Go 1.25+
• ✅ High performance
• ✅ Well tested
• ✅ Comprehensive docs

🔗 Related Links

External Resources

• Go HTTP Package
• Go 1.22 Routing Enhancements
• Semantic Versioning
• Keep a Changelog

Middleware Compatibility

• Gorilla Handlers
• Chi Middleware

💡 Tips

Finding Information

• General usage: Start with README.md
• Quick start: Use QUICKSTART.md
• Contributing: Read CONTRIBUTING.md
• Changes: Check CHANGELOG.md
• Examples: See example/ directory

Getting Help

1. Check the documentation
2. Review examples
3. Search existing issues
4. Open a new issue with details

📝 License

This project is licensed under the MIT License - see LICENSE for details.

---

Note: All documentation files are written in Markdown and can be viewed on GitHub or in any Markdown viewer.

Last Updated: 2024