diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1c723c6..623665ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## Contributing +# Contributing - With issues: - Use the search tool before opening a new issue. diff --git a/README.md b/README.md index 94e08a78..a24b349f 100644 --- a/README.md +++ b/README.md @@ -9,46 +9,48 @@ [![Sourcegraph](https://sourcegraph.com/github.com/gin-gonic/gin/-/badge.svg)](https://sourcegraph.com/github.com/gin-gonic/gin?badge) [![Open Source Helpers](https://www.codetriage.com/gin-gonic/gin/badges/users.svg)](https://www.codetriage.com/gin-gonic/gin) [![Release](https://img.shields.io/github/release/gin-gonic/gin.svg?style=flat-square)](https://github.com/gin-gonic/gin/releases) -[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/gin-gonic/gin)](https://www.tickgit.com/browse?repo=github.com/gin-gonic/gin) -Gin is a web framework written in [Go](https://go.dev/). It features a martini-like API with performance that is up to 40 times faster thanks to [httprouter](https://github.com/julienschmidt/httprouter). -If you need performance and good productivity, you will love Gin. +Gin is a high-performance HTTP web framework written in [Go](https://go.dev/). It provides a Martini-like API but with significantly better performance—up to 40 times faster—thanks to [httprouter](https://github.com/julienschmidt/httprouter). Gin is designed for building REST APIs, web applications, and microservices where speed and developer productivity are essential. -**Gin's key features are:** +**Why choose Gin?** -- Zero allocation router -- Speed -- Middleware support -- Crash-free -- JSON validation -- Route grouping -- Error management -- Built-in rendering -- Extensible +Gin combines the simplicity of Express.js-style routing with Go's performance characteristics, making it ideal for: -## Getting started +- Building high-throughput REST APIs +- Developing microservices that need to handle many concurrent requests +- Creating web applications that require fast response times +- Prototyping web services quickly with minimal boilerplate + +**Gin's key features:** + +- **Zero allocation router** - Extremely memory-efficient routing with no heap allocations +- **High performance** - Benchmarks show superior speed compared to other Go web frameworks +- **Middleware support** - Extensible middleware system for authentication, logging, CORS, etc. +- **Crash-free** - Built-in recovery middleware prevents panics from crashing your server +- **JSON validation** - Automatic request/response JSON binding and validation +- **Route grouping** - Organize related routes and apply common middleware +- **Error management** - Centralized error handling and logging +- **Built-in rendering** - Support for JSON, XML, HTML templates, and more +- **Extensible** - Large ecosystem of community middleware and plugins + +## Getting Started ### Prerequisites -Gin requires [Go](https://go.dev/) version [1.23](https://go.dev/doc/devel/release#go1.23.0) or above. +- **Go version**: Gin requires [Go](https://go.dev/) version [1.23](https://go.dev/doc/devel/release#go1.23.0) or above +- **Basic Go knowledge**: Familiarity with Go syntax and package management is helpful -### Getting Gin +### Installation -With [Go's module support](https://go.dev/wiki/Modules#how-to-use-modules), `go [build|run|test]` automatically fetches the necessary dependencies when you add the import in your code: +With [Go's module support](https://go.dev/wiki/Modules#how-to-use-modules), simply import Gin in your code and Go will automatically fetch it during build: -```sh +```go import "github.com/gin-gonic/gin" ``` -Alternatively, use `go get`: +### Your First Gin Application -```sh -go get -u github.com/gin-gonic/gin -``` - -### Running Gin - -A basic example: +Here's a complete example that demonstrates Gin's simplicity: ```go package main @@ -60,59 +62,80 @@ import ( ) func main() { + // Create a Gin router with default middleware (logger and recovery) r := gin.Default() + + // Define a simple GET endpoint r.GET("/ping", func(c *gin.Context) { + // Return JSON response c.JSON(http.StatusOK, gin.H{ "message": "pong", }) }) - r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") + + // Start server on port 8080 (default) + // Server will listen on 0.0.0.0:8080 (localhost:8080 on Windows) + r.Run() } ``` -To run the code, use the `go run` command, like: +**Running the application:** -```sh -go run example.go -``` +1. Save the code above as `main.go` +2. Run the application: -Then visit [`0.0.0.0:8080/ping`](http://0.0.0.0:8080/ping) in your browser to see the response! + ```sh + go run main.go + ``` -### See more examples +3. Open your browser and visit [`http://localhost:8080/ping`](http://localhost:8080/ping) +4. You should see: `{"message":"pong"}` -#### Quick Start +**What this example demonstrates:** -Learn and practice with the [Gin Quick Start](docs/doc.md), which includes API examples and builds tag. +- Creating a Gin router with default middleware +- Defining HTTP endpoints with simple handler functions +- Returning JSON responses +- Starting an HTTP server -#### Examples +### Next Steps -A number of ready-to-run examples demonstrating various use cases of Gin are available in the [Gin examples](https://github.com/gin-gonic/examples) repository. +After running your first Gin application, explore these resources to learn more: -## Documentation +#### 📚 Learning Resources -See the [API documentation on go.dev](https://pkg.go.dev/github.com/gin-gonic/gin). +- **[Gin Quick Start Guide](docs/doc.md)** - Comprehensive tutorial with API examples and build configurations +- **[Example Repository](https://github.com/gin-gonic/examples)** - Ready-to-run examples demonstrating various Gin use cases: + - REST API development + - Authentication & middleware + - File uploads and downloads + - WebSocket connections + - Template rendering -The documentation is also available on [gin-gonic.com](https://gin-gonic.com) in several languages: +## 📖 Documentation -- [English](https://gin-gonic.com/en/docs/) -- [简体中文](https://gin-gonic.com/zh-cn/docs/) -- [繁體中文](https://gin-gonic.com/zh-tw/docs/) -- [日本語](https://gin-gonic.com/ja/docs/) -- [Español](https://gin-gonic.com/es/docs/) -- [한국어](https://gin-gonic.com/ko-kr/docs/) -- [Turkish](https://gin-gonic.com/tr/docs/) -- [Persian](https://gin-gonic.com/fa/docs/) -- [Português](https://gin-gonic.com/pt/docs/) -- [Russian](https://gin-gonic.com/ru/docs/) -- [Indonesian](https://gin-gonic.com/id/docs/) +### API Reference -### Articles +- **[Go.dev API Documentation](https://pkg.go.dev/github.com/gin-gonic/gin)** - Complete API reference with examples -- [Tutorial: Developing a RESTful API with Go and Gin](https://go.dev/doc/tutorial/web-service-gin) +### User Guides -## Benchmarks +The comprehensive documentation is available on [gin-gonic.com](https://gin-gonic.com) in multiple languages: -Gin uses a custom version of [HttpRouter](https://github.com/julienschmidt/httprouter), [see all benchmarks](/BENCHMARKS.md). +- [English](https://gin-gonic.com/en/docs/) | [简体中文](https://gin-gonic.com/zh-cn/docs/) | [繁體中文](https://gin-gonic.com/zh-tw/docs/) +- [日本語](https://gin-gonic.com/ja/docs/) | [한국어](https://gin-gonic.com/ko-kr/docs/) | [Español](https://gin-gonic.com/es/docs/) +- [Turkish](https://gin-gonic.com/tr/docs/) | [Persian](https://gin-gonic.com/fa/docs/) | [Português](https://gin-gonic.com/pt/docs/) +- [Russian](https://gin-gonic.com/ru/docs/) | [Indonesian](https://gin-gonic.com/id/docs/) + +### Official Tutorials + +- [Go.dev Tutorial: Developing a RESTful API with Go and Gin](https://go.dev/doc/tutorial/web-service-gin) + +## ⚡ Performance Benchmarks + +Gin demonstrates exceptional performance compared to other Go web frameworks. It uses a custom version of [HttpRouter](https://github.com/julienschmidt/httprouter) for maximum efficiency. [View detailed benchmarks →](/BENCHMARKS.md) + +**Gin vs. Other Go Frameworks** (GitHub API routing benchmark): | Benchmark name | (1) | (2) | (3) | (4) | | ------------------------------ | --------: | --------------: | -----------: | --------------: | @@ -152,23 +175,44 @@ Gin uses a custom version of [HttpRouter](https://github.com/julienschmidt/httpr - (3): Heap Memory (B/op), lower is better - (4): Average Allocations per Repetition (allocs/op), lower is better -## Middleware +## 🔌 Middleware Ecosystem -You can find many useful Gin middlewares at [gin-contrib](https://github.com/gin-contrib) and [gin-gonic/contrib](https://github.com/gin-gonic/contrib). +Gin has a rich ecosystem of middleware for common web development needs. Explore community-contributed middleware: -## Uses +- **[gin-contrib](https://github.com/gin-contrib)** - Official middleware collection including: + - Authentication (JWT, Basic Auth, Sessions) + - CORS, Rate limiting, Compression + - Logging, Metrics, Tracing + - Static file serving, Template engines + +- **[gin-gonic/contrib](https://github.com/gin-gonic/contrib)** - Additional community middleware -Here are some awesome projects that are using the [Gin](https://github.com/gin-gonic/gin) web framework. +## 🏢 Production Usage -- [gorush](https://github.com/appleboy/gorush): A push notification server. -- [fnproject](https://github.com/fnproject/fn): A container native, cloud agnostic serverless platform. -- [photoprism](https://github.com/photoprism/photoprism): Personal photo management powered by Google TensorFlow. -- [lura](https://github.com/luraproject/lura): Ultra performant API Gateway with middleware. -- [picfit](https://github.com/thoas/picfit): An image resizing server. -- [dkron](https://github.com/distribworks/dkron): Distributed, fault tolerant job scheduling system. +Gin powers many high-traffic applications and services in production: -## Contributing +- **[gorush](https://github.com/appleboy/gorush)** - High-performance push notification server +- **[fnproject](https://github.com/fnproject/fn)** - Container-native, serverless platform +- **[photoprism](https://github.com/photoprism/photoprism)** - AI-powered personal photo management +- **[lura](https://github.com/luraproject/lura)** - Ultra-performant API Gateway framework +- **[picfit](https://github.com/thoas/picfit)** - Real-time image processing server +- **[dkron](https://github.com/distribworks/dkron)** - Distributed job scheduling system -Gin is the work of hundreds of contributors. We appreciate your help! +## 🤝 Contributing -Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on submitting patches and the contribution workflow. +Gin is the work of hundreds of contributors from around the world. We welcome and appreciate your contributions! + +### How to Contribute + +- 🐛 **Report bugs** - Help us identify and fix issues +- 💡 **Suggest features** - Share your ideas for improvements +- 📝 **Improve documentation** - Help make our docs clearer +- 🔧 **Submit code** - Fix bugs or implement new features +- 🧪 **Write tests** - Improve our test coverage + +### Getting Started with Contributing + +1. Check out our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines +2. Join our community discussions and ask questions + +**All contributions are valued and help make Gin better for everyone!**