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

2026-05-07 06:59:59 +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. 上海晓信信息科技有限公司（晓黑板）