docs(readme): revamp and expand documentation for clarity and completeness (#4362)

- Update contributing header to single hash style - Remove deprecated badge and improve project summary wording - Reorganize and clarify feature descriptions and benefits - Restructure getting started and installation instructions for clarity - Expand and annotate the first example application walkthrough - Detail the steps for running the sample application and expected output - Improve guidance on learning resources and example projects - Enhance API reference, documentation links, and tutorial references - Add a clear performance benchmarks section comparing Gin to other frameworks - Expand middleware section with ecosystem highlights and usage details - Create a production usage section listing notable projects using Gin - Revamp contribution section with clearer procedure and encouragement for new contributors Signed-off-by: appleboy <appleboy.tw@gmail.com>
2025-10-12 02:58:08 +08:00 · 2025-09-20 20:58:46 +08:00 · 2025-09-20 20:58:46 +08:00 · 4dd00f81b1
commit 4dd00f81b1
parent 6ad6205e9c
2 changed files with 113 additions and 69 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -1,4 +1,4 @@
-## Contributing
+# Contributing

 - With issues:
  - Use the search tool before opening a new issue.
--- 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!**