docs: simplify README files while preserving structure (#5338)

2026-01-24 10:33:28 +08:00 · 2025-12-13 13:01:35 +08:00
parent b284664de4
commit 5c9ea81db2
2 changed files with 92 additions and 240 deletions
--- a/readme-cn.md
+++ b/readme-cn.md
@@ -25,62 +25,41 @@ go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的

 使用 go-zero 的好处：

-* 轻松获得支撑千万日活服务的稳定性
-* 内建级联超时控制、限流、自适应熔断、自适应降载等微服务治理能力，无需配置和额外代码
-* 微服务治理中间件可无缝集成到其它现有框架使用
-* 极简的 API 描述，一键生成各端代码
-* 自动校验客户端请求参数合法性
-* 大量微服务治理和并发工具包
+* 经过千万日活服务验证的稳定性
+* 内建弹性保护:级联超时、限流、熔断、降载(无需配置)
+* 极简 API 语法生成多端代码
+* 自动参数校验和丰富的微服务工具包

 ![架构图](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/architecture.png)

 ## go-zero 框架背景

-18 年初，我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构，经过仔细思考和对比，我们决定：
+18 年初,我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构,选择:

-* 基于 Go 语言
-  * 高效的性能
-  * 简洁的语法
-  * 广泛验证的工程效率
-  * 极致的部署体验
-  * 极低的服务端资源成本
-* 自研微服务框架
-  * 有过很多微服务框架自研经验
-  * 需要有更快速的问题定位能力
-  * 更便捷的增加新特性
+* **基于 Go 语言** - 高效性能、简洁语法、极致部署体验、极低资源成本
+* **自研微服务框架** - 更快速的问题定位、更便捷的新特性增加

 ## go-zero 框架设计思考

-对于微服务框架的设计，我们期望保障微服务稳定性的同时，也要特别注重研发效率。所以设计之初，我们就有如下一些准则：
+go-zero 遵循以下核心设计准则:

-* 保持简单，第一原则
-* 弹性设计，面向故障编程
-* 工具大于约定和文档
-* 高可用、高并发、易扩展
-* 对业务开发友好，封装复杂度
-* 约束做一件事只有一种方式
-
-我们经历不到半年时间，彻底完成了从 `Java+MongoDB` 到 `Golang+MySQL` 为主的微服务体系迁移，并于 18 年 8 月底完全上线，稳定保障了业务后续迅速增长，确保了整个服务的高可用。
+* **保持简单** - 简单是第一原则
+* **高可用** - 高并发、易扩展
+* **弹性设计** - 面向故障编程
+* **工具驱动** - 工具大于约定和文档
+* **业务友好** - 封装复杂度、一事一法

 ## go-zero 项目实现和特点

-go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有如下主要特点：
+go-zero 集成各种工程实践,主要特点:

-* 强大的工具支持，尽可能少的代码编写
-* 极简的接口
-* 完全兼容 net/http
-* 支持中间件，方便扩展
-* 高性能
-* 面向故障编程，弹性设计
-* 内建服务发现、负载均衡
-* 内建限流、熔断、降载，且自动触发，自动恢复
-* API 参数自动校验
-* 超时级联控制
-* 自动缓存控制
-* 链路跟踪、统计报警等
-* 高并发支撑，稳定保障了疫情期间每天的流量洪峰
+* **强大工具支持** - 尽可能少的代码编写
+* **极简接口** - 完全兼容 net/http
+* **高性能** - 优化的速度和效率
+* **弹性设计** - 内建限流、熔断、降载,自动触发、自动恢复
+* **服务治理** - 内建服务发现、负载均衡、链路跟踪
+* **开发工具** - API 参数自动校验、超时级联控制、自动缓存控制

-如下图，我们从多个层面保障了整体服务的高可用：

 ![弹性设计](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/resilience.jpg)

@@ -100,104 +79,53 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro

 ## AI 原生开发

-让大模型成为你的 go-zero 专家！go-zero 团队构建了完整的 AI 工具生态，包括 **ai-context**、**zero-skills** 和 **mcp-zero** 三个项目，让 Claude、GitHub Copilot、Cursor 等 AI 编程助手生成符合 go-zero 规范的代码。
+go-zero 团队构建了完整的 AI 工具生态,让 Claude、GitHub Copilot、Cursor 生成符合 go-zero 规范的代码。

 ### 三大核心项目

-**[ai-context](https://github.com/zeromicro/ai-context)** - AI 的"工作手册"
- 告诉 AI 助手**什么时候做什么**
- 工作流程和决策树的快速参考
- 专为 GitHub Copilot 优化（通过 `.github/copilot-instructions.md`）
+**[ai-context](https://github.com/zeromicro/ai-context)** - AI 的工作流程指南

-**[zero-skills](https://github.com/zeromicro/zero-skills)** - AI 的"技术百科"
- 提供**详细模式**和完整示例
- ✅ 正确做法 vs ❌ 错误做法对比
- 涵盖 REST API、RPC、数据库、弹性保护等
+**[zero-skills](https://github.com/zeromicro/zero-skills)** - 模式库和示例

-**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - AI 的"实时助手"
- 让 AI 能**真正动手做**：生成代码、分析项目
- 基于 Model Context Protocol (MCP)
- 与 Claude Desktop 深度集成
+**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - 基于 MCP 的代码生成工具

 ### 快速配置

 #### GitHub Copilot
 ```bash
-# 添加 ai-context 作为 submodule
 git submodule add https://github.com/zeromicro/ai-context.git .github/ai-context
-
-# 创建符号链接（macOS/Linux）
-ln -s ai-context/00-instructions.md .github/copilot-instructions.md
-
-# Windows 用户使用
-mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
-
-# 更新到最新版本
-git submodule update --remote .github/ai-context
+ln -s ai-context/00-instructions.md .github/copilot-instructions.md  # macOS/Linux
+# Windows: mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
+git submodule update --remote .github/ai-context  # 更新
 ```

 #### Cursor
 ```bash
-# 添加 ai-context 作为 submodule
 git submodule add https://github.com/zeromicro/ai-context.git .cursorrules
-
-# 更新到最新版本
-git submodule update --remote .cursorrules
+git submodule update --remote .cursorrules  # 更新
 ```

-#### Windsurf (Codeium)
+#### Windsurf
 ```bash
-# 添加 ai-context 作为 submodule
 git submodule add https://github.com/zeromicro/ai-context.git .windsurfrules
-
-# 更新到最新版本
-git submodule update --remote .windsurfrules
+git submodule update --remote .windsurfrules  # 更新
 ```

-#### Claude Desktop + mcp-zero
+#### Claude Desktop
 ```bash
-# 安装 mcp-zero
-git clone https://github.com/zeromicro/mcp-zero.git
-cd mcp-zero
-go build -o mcp-zero main.go
-
-# 配置 Claude Desktop（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）
-# 在 mcpServers 中添加：
-{
-  "mcpServers": {
-    "mcp-zero": {
-      "command": "/path/to/mcp-zero",
-      "env": {
-        "GOCTL_PATH": "/Users/yourname/go/bin/goctl"
-      }
-    }
-  }
-}
-```
-
-或使用 Claude 命令行：
-```bash
-# 通过 CLI 添加 mcp-zero 服务器
-claude mcp add \
-  --transport stdio \
-  mcp-zero \
-  --env GOCTL_PATH=/Users/yourname/go/bin/goctl \
-  -- /path/to/mcp-zero
+git clone https://github.com/zeromicro/mcp-zero.git && cd mcp-zero && go build
+# 配置: ~/Library/Application Support/Claude/claude_desktop_config.json
+# 或: claude mcp add --transport stdio mcp-zero --env GOCTL_PATH=/path/to/goctl -- /path/to/mcp-zero
 ```

 ### 协同工作原理

-AI 助手通过这三个工具协同配合，提供完整的开发体验：
+AI 助手通过三个工具协同配合:
+1. **ai-context** - 工作流程指导
+2. **zero-skills** - 实现模式
+3. **mcp-zero** - 实时代码生成

-1. **ai-context** 提供工作流程指导和快速模式
-2. **zero-skills** 提供详细实现和最佳实践
-3. **mcp-zero** 提供实时代码生成和项目分析
-
-**示例**：创建新的 REST API
- AI 读取 **ai-context** → 了解应该用 `create_api_service` 工具
- AI 调用 **mcp-zero** → 执行生成项目结构
- AI 参考 **zero-skills** → 获取完整的 Handler/Logic/Context 三层架构模式
- 结果：符合 go-zero 规范的生产级代码 ✅
+**示例**:创建新的 REST API → AI 读取 **ai-context** 了解工作流 → 调用 **mcp-zero** 生成代码 → 参考 **zero-skills** 实现模式 → 生成符合规范的代码 ✅

 ## Quick Start

@@ -209,7 +137,6 @@ AI 助手通过这三个工具协同配合，提供完整的开发体验：

 1. 安装 goctl 工具

-    `goctl` 读作 `go control`，不要读成 `go C-T-L`。`goctl` 的意思是不要被代码控制，而是要去控制它。其中的 `go` 不是指 `golang`。在设计 `goctl` 之初，我就希望通过 `工具` 来解放我们的双手👈

    ```shell
    # Go
@@ -224,7 +151,7 @@ AI 助手通过这三个工具协同配合，提供完整的开发体验：
    docker run --rm -it -v `pwd`:/app kevinwan/goctl --help
    ```

-    确保 goctl 可执行，并且在 $PATH 环境变量里。
+    确保 goctl 可执行并在 $PATH 环境变量里。

 2. 快速生成 api 服务

@@ -258,7 +185,7 @@ AI 助手通过这三个工具协同配合，提供完整的开发体验：
      * 可以在 `servicecontext.go` 里面传递依赖给 logic，比如 mysql, redis 等
      * 在 api 定义的 `get/post/put/delete` 等请求对应的 logic 里增加业务处理逻辑

-3. 可以根据 api 文件生成前端需要的 Java, TypeScript, Dart, JavaScript 代码
+3. 生成多语言客户端代码

    ```shell
    goctl api java -api greet.api -dir greet
@@ -295,7 +222,7 @@ AI 助手通过这三个工具协同配合，提供完整的开发体验：

 ## go-zero 用户

-go-zero 已被许多公司用于生产部署，接入场景如在线教育、电商业务、游戏、区块链等，目前为止，已使用 go-zero 的公司包括但不限于：
+go-zero 已被众多公司用于生产部署,场景涵盖在线教育、电商、游戏、区块链等。目前使用 go-zero 的公司包括但不限于:

 >1. 好未来
 >2. 上海晓信信息科技有限公司（晓黑板）
--- a/readme.md
+++ b/readme.md
@@ -42,57 +42,35 @@ go-zero contains simple API description syntax and code generation tool called `

 ## Backgrounds of go-zero

-In early 2018, we embarked on a transformative journey to redesign our system, transitioning from a monolithic architecture built with Java and MongoDB to a microservices architecture. After careful research and comparison, we made a deliberate choice to:
+In early 2018, we transitioned from a Java+MongoDB monolithic architecture to microservices, choosing:

-* Go Beyond with Golang
-  * Great performance
-  * Simple syntax
-  * Proven engineering efficiency
-  * Extreme deployment experience
-  * Less server resource consumption
-
-* Self-Design Our Microservice Architecture
-  * Microservice architecture facilitates the creation of scalable, flexible, and maintainable software systems with independent, reusable components.
-  * Easy to locate the problems within microservices.
-  * Easy to extend the features by adding or modifying specific microservices without impacting the entire system.
+* **Golang** - High performance, simple syntax, excellent deployment experience, and low resource consumption
+* **Self-designed microservice framework** - Better problem isolation, easier feature extension, and faster issue resolution

 ## Design considerations on go-zero

-By designing the microservice architecture, we expected to ensure stability, as well as productivity. And from just the beginning, we have the following design principles:
+go-zero follows these core design principles:

-* Keep it simple
-* High availability
-* Stable on high concurrency
-* Easy to extend
-* Resilience design, failure-oriented programming
-* Try best to be friendly to the business logic development, encapsulate the complexity
-* One thing, one way
-
-After almost half a year, we finished the transfer from a monolithic system to microservice system and deployed on August 2018. The new system guaranteed business growth and system stability.
+* **Simplicity** - Keep it simple, first principle
+* **High availability** - Stable under high concurrency
+* **Resilience** - Failure-oriented programming with adaptive protection
+* **Developer friendly** - Encapsulate complexity, one way to do one thing
+* **Easy to extend** - Flexible architecture for growth

 ## The implementation and features of go-zero

-go-zero is a web and rpc framework that integrates lots of engineering practices. The features are mainly listed below:
+go-zero integrates engineering best practices:

-* Powerful tool included, less code to write
-* Simple interfaces
-* Fully compatible with net/http
-* Middlewares are supported, easy to extend
-* High performance
-* Failure-oriented programming, resilience design
-* Builtin service discovery, load balancing
-* Builtin concurrency control, adaptive circuit breaker, adaptive load shedding, auto-trigger, auto recover
-* Auto validation of API request parameters
-* Chained timeout control
-* Auto management of data caching
-* Call tracing, metrics, and monitoring
-* High concurrency protected
-
-As below, go-zero protects the system with a couple of layers and mechanisms:
+* **Code generation** - Powerful tools to minimize boilerplate
+* **Simple API** - Clean interfaces, fully compatible with net/http
+* **High performance** - Optimized for speed and efficiency
+* **Resilience** - Built-in circuit breaker, rate limiting, load shedding, timeout control
+* **Service mesh** - Service discovery, load balancing, call tracing
+* **Developer tools** - Auto parameter validation, cache management, metrics and monitoring

 ![Resilience](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/resilience-en.png)

-## The simplified architecture that we use with go-zero
+## Architecture with go-zero

 <img width="1067" alt="image" src="https://user-images.githubusercontent.com/1918356/171880372-5010d846-e8b1-4942-8fe2-e2bbb584f762.png">

@@ -106,108 +84,57 @@ go get -u github.com/zeromicro/go-zero

 ## AI-Native Development

-Make AI assistants (Claude, GitHub Copilot, Cursor, etc.) your go-zero experts! The go-zero team provides a complete AI tooling ecosystem to generate framework-compliant code and boost your productivity.
+The go-zero team provides AI tooling for Claude, GitHub Copilot, Cursor to generate framework-compliant code.

 ### Three Core Projects

-**[ai-context](https://github.com/zeromicro/ai-context)** - AI's "Workflow Guide"
- Tells AI assistants **when and how** to use go-zero tools
- Quick reference for code patterns and decision trees
- Optimized for GitHub Copilot via `.github/copilot-instructions.md`
+**[ai-context](https://github.com/zeromicro/ai-context)** - Workflow guide for AI assistants

-**[zero-skills](https://github.com/zeromicro/zero-skills)** - AI's "Knowledge Base"
- Provides **detailed patterns** with complete examples
- Shows ✅ correct patterns vs ❌ common mistakes
- Covers REST APIs, RPC, databases, and resilience patterns
+**[zero-skills](https://github.com/zeromicro/zero-skills)** - Pattern library with examples

-**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - AI's "Runtime Tools"
- Enables AI to **execute actions**: generate code, analyze projects
- Based on Model Context Protocol (MCP)
- Deep integration with Claude Desktop
+**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - Code generation tools via Model Context Protocol

 ### Quick Setup

 #### GitHub Copilot
 ```bash
-# Add ai-context as a submodule
 git submodule add https://github.com/zeromicro/ai-context.git .github/ai-context
-
-# Create symbolic link (macOS/Linux)
-ln -s ai-context/00-instructions.md .github/copilot-instructions.md
-
-# Windows
-mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
-
-# Update to latest version
-git submodule update --remote .github/ai-context
+ln -s ai-context/00-instructions.md .github/copilot-instructions.md  # macOS/Linux
+# Windows: mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md
+git submodule update --remote .github/ai-context  # Update
 ```

 #### Cursor
 ```bash
-# Add ai-context as project rules
 git submodule add https://github.com/zeromicro/ai-context.git .cursorrules
-
-# Update to latest
-git submodule update --remote .cursorrules
+git submodule update --remote .cursorrules  # Update
 ```

-#### Windsurf (Codeium)
+#### Windsurf
 ```bash
-# Add ai-context for Windsurf
 git submodule add https://github.com/zeromicro/ai-context.git .windsurfrules
-
-# Update to latest
-git submodule update --remote .windsurfrules
+git submodule update --remote .windsurfrules  # Update
 ```

-#### Claude Desktop + mcp-zero
+#### Claude Desktop
 ```bash
-# Install mcp-zero
-git clone https://github.com/zeromicro/mcp-zero.git
-cd mcp-zero
-go build -o mcp-zero main.go
-
-# Configure Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)
-# Add to mcpServers:
-{
-  "mcpServers": {
-    "mcp-zero": {
-      "command": "/path/to/mcp-zero",
-      "env": {
-        "GOCTL_PATH": "/Users/yourname/go/bin/goctl"
-      }
-    }
-  }
-}
-```
-
-Or use Claude CLI:
-```bash
-# Add mcp-zero server via CLI
-claude mcp add \
-  --transport stdio \
-  mcp-zero \
-  --env GOCTL_PATH=/Users/yourname/go/bin/goctl \
-  -- /path/to/mcp-zero
+git clone https://github.com/zeromicro/mcp-zero.git && cd mcp-zero && go build
+# Configure: ~/Library/Application Support/Claude/claude_desktop_config.json
+# Or: claude mcp add --transport stdio mcp-zero --env GOCTL_PATH=/path/to/goctl -- /path/to/mcp-zero
 ```

 ### How It Works

-AI assistants use these tools together for a complete development experience:
+AI assistants use these tools together:
+1. **ai-context** - workflow guidance
+2. **zero-skills** - implementation patterns
+3. **mcp-zero** - real-time code generation

-1. **ai-context** provides workflow guidance and quick patterns
-2. **zero-skills** supplies detailed implementations and best practices
-3. **mcp-zero** enables real-time code generation and project analysis
-
-**Example**: Creating a new REST API
- AI reads **ai-context** → knows to use `create_api_service` tool
- AI calls **mcp-zero** → generates project structure
- AI references **zero-skills** → implements handlers with correct patterns
- Result: Production-ready code following go-zero conventions ✅
+**Example**: Creating a REST API → AI reads **ai-context** for workflow → calls **mcp-zero** to generate code → references **zero-skills** for patterns → produces production-ready code ✅

 ## Quick Start

-1. Full examples can be checked out from below:
+1. Full examples:

     [Rapid development of microservice systems](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md)

@@ -215,8 +142,6 @@ AI assistants use these tools together for a complete development experience:

 2. Install goctl

-   `goctl`can be read as `go control`. `goctl` means not to be controlled by code, instead, we control it. The inside `go` is not `golang`. At the very beginning, I was expecting it to help us improve productivity, and make our lives easier.
-
   ```shell
   # for Go
   go install github.com/zeromicro/go-zero/tools/goctl@latest
@@ -230,9 +155,9 @@ AI assistants use these tools together for a complete development experience:
   docker run --rm -it -v `pwd`:/app kevinwan/goctl --help
   ```

-   make sure goctl is executable and in your $PATH.
+   Ensure goctl is executable and in your $PATH.

-3. Create the API file, like greet.api, you can install the plugin of goctl in vs code, api syntax is supported.
+3. Create the API file (greet.api):

   ```go
   type (
@@ -251,19 +176,19 @@ AI assistants use these tools together for a complete development experience:
   }
   ```

-   the .api files also can be generated by goctl, like below:
+   Generate .api template:

   ```shell
   goctl api -o greet.api
   ```

-4. Generate the go server-side code
+4. Generate Go server code

   ```shell
   goctl api go -api greet.api -dir greet
   ```

-   the generated files look like:
+   Generated structure:

   ```Plain Text
   ├── greet
@@ -285,7 +210,7 @@ AI assistants use these tools together for a complete development experience:
   └── greet.api                     // api description file
   ```

-   the generated code can be run directly:
+   Run the service:

   ```shell
   cd greet
@@ -293,15 +218,15 @@ AI assistants use these tools together for a complete development experience:
   go run greet.go -f etc/greet-api.yaml
   ```

-   by default, it’s listening on port 8888, while it can be changed in the configuration file.
+   Default port: 8888 (configurable in etc/greet-api.yaml)

-   you can check it by curl:
+   Test with curl:

   ```shell
   curl -i http://localhost:8888/greet/from/you
   ```

-   the response looks like below:
+   Response:

   ```http
   HTTP/1.1 200 OK
@@ -309,12 +234,12 @@ AI assistants use these tools together for a complete development experience:
   Content-Length: 0
   ```

-5. Write the business logic code
+5. Write business logic

-    * the dependencies can be passed into the logic within servicecontext.go, like mysql, redis, etc.
-    * add the logic code in a logic package according to .api file
+    * Pass dependencies (mysql, redis, etc.) via servicecontext.go
+    * Add logic code in the logic package per .api definition

-6. Generate code like Java, TypeScript, Dart, JavaScript, etc. just from the api file
+6. Generate client code for multiple languages

   ```shell
   goctl api java -api greet.api -dir greet