+
+# go-zero
+
+[](https://github.com/zeromicro/go-zero/actions)
+[](https://goreportcard.com/report/github.com/tal-tech/go-zero)
+[](https://goproxy.cn/stats/github.com/tal-tech/go-zero/badges/download-count.svg)
+[](https://codecov.io/gh/tal-tech/go-zero)
+[](https://github.com/zeromicro/go-zero)
+[](https://opensource.org/licenses/MIT)
+
+## 0. go-zero 介绍
+
+go-zero 是一个集成了各种工程实践的 web 和 rpc 框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。
+
+go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 api 文件一键生成 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 代码，并可直接运行。
+
+使用 go-zero 的好处：
+
+* 轻松获得支撑千万日活服务的稳定性
+* 内建级联超时控制、限流、自适应熔断、自适应降载等微服务治理能力，无需配置和额外代码
+* 微服务治理中间件可无缝集成到其它现有框架使用
+* 极简的 API 描述，一键生成各端代码
+* 自动校验客户端请求参数合法性
+* 大量微服务治理和并发工具包
+
+
+
+## 1. go-zero 框架背景
+
+18 年初，我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构，经过仔细思考和对比，我们决定：
+
+* 基于 Go 语言
+ * 高效的性能
+ * 简洁的语法
+ * 广泛验证的工程效率
+ * 极致的部署体验
+ * 极低的服务端资源成本
+* 自研微服务框架
+ * 有过很多微服务框架自研经验
+ * 需要有更快速的问题定位能力
+ * 更便捷的增加新特性
+
+## 2. go-zero 框架设计思考
+
+对于微服务框架的设计，我们期望保障微服务稳定性的同时，也要特别注重研发效率。所以设计之初，我们就有如下一些准则：
+
+* 保持简单，第一原则
+* 弹性设计，面向故障编程
+* 工具大于约定和文档
+* 高可用
+* 高并发
+* 易扩展
+* 对业务开发友好，封装复杂度
+* 约束做一件事只有一种方式
+
+我们经历不到半年时间，彻底完成了从 `Java+MongoDB` 到 `Golang+MySQL` 为主的微服务体系迁移，并于 18 年 8 月底完全上线，稳定保障了业务后续迅速增长，确保了整个服务的高可用。
+
+## 3. go-zero 项目实现和特点
+
+go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有如下主要特点：
+
+* 强大的工具支持，尽可能少的代码编写
+* 极简的接口
+* 完全兼容 net/http
+* 支持中间件，方便扩展
+* 高性能
+* 面向故障编程，弹性设计
+* 内建服务发现、负载均衡
+* 内建限流、熔断、降载，且自动触发，自动恢复
+* API 参数自动校验
+* 超时级联控制
+* 自动缓存控制
+* 链路跟踪、统计报警等
+* 高并发支撑，稳定保障了疫情期间每天的流量洪峰
+
+如下图，我们从多个层面保障了整体服务的高可用：
+
+
+
+觉得不错的话，别忘 **star** 👏
+
+## 4. Installation
+
+在项目目录下通过如下命令安装：
+
+```shell
+GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero
+```
+
+## 5. Quick Start
+
+0. 完整示例请查看
+
+ [快速构建高并发微服务](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl.md)
+
+ [快速构建高并发微服务 - 多 RPC 版](https://github.com/tal-tech/zero-doc/blob/main/docs/zero/bookstore.md)
+
+1. 安装 goctl 工具
+
+ `goctl` 读作 `go control`，不要读成 `go C-T-L`。`goctl` 的意思是不要被代码控制，而是要去控制它。其中的 `go` 不是指 `golang`。在设计 `goctl` 之初，我就希望通过 ` 她 `
+ 来解放我们的双手👈
+
+ ```shell
+ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl
+ ```
+
+ 如果使用 go1.16 版本, 可以使用 `go install` 命令安装
+
+ ```shell
+ GOPROXY=https://goproxy.cn/,direct go install github.com/tal-tech/go-zero/tools/goctl@latest
+ ```
+
+ 确保 goctl 可执行
+
+2. 快速生成 api 服务
+
+ ```shell
+ goctl api new greet
+ cd greet
+ go mod init
+ go mod tidy
+ go run greet.go -f etc/greet-api.yaml
+ ```
+
+ 默认侦听在 8888 端口（可以在配置文件里修改），可以通过 curl 请求：
+
+ ```shell
+ curl -i http://localhost:8888/from/you
+ ```
+
+ 返回如下：
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Thu, 22 Oct 2020 14:03:18 GMT
+ Content-Length: 14
+
+ {"message":""}
+ ```
+
+ 编写业务代码：
+
+ * api 文件定义了服务对外暴露的路由，可参考 [api 规范](https://github.com/tal-tech/zero-doc/blob/main/doc/goctl.md)
+ * 可以在 servicecontext.go 里面传递依赖给 logic，比如 mysql, redis 等
+ * 在 api 定义的 get/post/put/delete 等请求对应的 logic 里增加业务处理逻辑
+
+3. 可以根据 api 文件生成前端需要的 Java, TypeScript, Dart, JavaScript 代码
+
+ ```shell
+ goctl api java -api greet.api -dir greet
+ goctl api dart -api greet.api -dir greet
+ ...
+ ```
+
+## 6. Benchmark
+
+
+
+[测试代码见这里](https://github.com/smallnest/go-web-framework-benchmark)
+
+## 7. 文档
+
+* [API 文档](api-grammar.md)
+
+* [goctl 使用帮助](goctl.md)
+
+* 常见问题
+
+ * 因为 `etcd` 和 `grpc` 兼容性问题，请使用 `grpc@v1.29.1`
+
+ `google.golang.org/grpc v1.29.1`
+
+ * 因为 `protobuf` 兼容性问题，请使用 `protocol-gen@v1.3.2`
+
+ `go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2`
+
+* awesome 系列（更多文章见『微服务实践』公众号）
+ * [快速构建高并发微服务](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl.md)
+ * [快速构建高并发微服务 - 多 RPC 版](https://github.com/tal-tech/zero-doc/blob/main/docs/zero/bookstore.md)
+
+* 精选 `goctl` 插件
+
+ 
diff --git a/go-zero.dev/cn/about-us.md b/go-zero.dev/cn/about-us.md
new file mode 100644
index 00000000..1b248049
--- /dev/null
+++ b/go-zero.dev/cn/about-us.md
@@ -0,0 +1,20 @@
+# 关于我们
+
+## go-zero
+go-zero 是一个集成了各种工程实践的 web 和 rpc 框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。
+
+go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 api 文件一键生成 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 代码，并可直接运行。
+
+## go-zero作者
+[
+
由此可见，在整个调用链中，中间的某一个环节出现异常就会引起上游调用服务出现一些列的问题，甚至导致整个调用链的服务都宕机，这是非常可怕的。因此一个服务作为调用方调用另一个服务时，为了防止被调用服务出现问题进而导致调用服务出现问题，所以调用服务需要进行自我保护，而保护的常用手段就是***熔断***
@@ -16,17 +16,17 @@
- 打开(Open)：在该状态下，发起请求时会立即返回错误，一般会启动一个超时计时器，当计时器超时后，状态切换到半打开状态，也可以设置一个定时器，定期的探测服务是否恢复
- 半打开(Half-Open)：在该状态下，允许应用程序一定数量的请求发往被调用服务，如果这些调用正常，那么可以认为被调用服务已经恢复正常，此时熔断器切换到关闭状态，同时需要重置计数。如果这部分仍有调用失败的情况，则认为被调用方仍然没有恢复，熔断器会切换到关闭状态，然后重置计数器，半打开状态能够有效防止正在恢复中的服务被突然大量请求再次打垮
-
+
服务治理中引入熔断机制，使得系统更加稳定和有弹性，在系统从错误中恢复的时候提供稳定性，并且减少了错误对系统性能的影响，可以快速拒绝可能导致错误的服务调用，而不需要等待真正的错误返回
### 熔断器引入
-上面介绍了熔断器的原理，在了解完原理后，你是否有思考我们如何引入熔断器呢？一种方案是在业务逻辑中可以加入熔断器，但显然是不够优雅也不够通用的，因此我们需要把熔断器集成在框架内，在[zRPC](https://github.com/tal-tech/go-zero/tree/master/zrpc)框架内就内置了熔断器
+上面介绍了熔断器的原理，在了解完原理后，你是否有思考我们如何引入熔断器呢？一种方案是在业务逻辑中可以加入熔断器，但显然是不够优雅也不够通用的，因此我们需要把熔断器集成在框架内，在[zRPC](https://github.com/zeromicro/go-zero/tree/master/zrpc)框架内就内置了熔断器
我们知道，熔断器主要是用来保护调用端，调用端在发起请求的时候需要先经过熔断器，而客户端拦截器正好兼具了这个这个功能，所以在zRPC框架内熔断器是实现在客户端拦截器内，拦截器的原理如下图：
-
+
对应的代码为：
@@ -52,7 +52,7 @@ zRPC中熔断器的实现参考了[Google Sre过载保护算法](https://landing
在正常情况下，这两个值是相等的，随着被调用方服务出现异常开始拒绝请求，请求接受数量(accepts)的值开始逐渐小于请求数量(requests)，这个时候调用方可以继续发送请求，直到requests = K * accepts，一旦超过这个限制，熔断器就回打开，新的请求会在本地以一定的概率被抛弃直接返回错误，概率的计算公式如下：
-
+
通过修改算法中的K(倍值)，可以调节熔断器的敏感度，当降低该倍值会使自适应熔断算法更敏感，当增加该倍值会使得自适应熔断算法降低敏感度，举例来说，假设将调用方的请求上限从 requests = 2 * acceptst 调整为 requests = 1.1 * accepts 那么就意味着调用方每十个请求之中就有一个请求会触发熔断
diff --git a/go-zero.dev/cn/buiness-cache.md b/go-zero.dev/cn/buiness-cache.md
new file mode 100644
index 00000000..927666f9
--- /dev/null
+++ b/go-zero.dev/cn/buiness-cache.md
@@ -0,0 +1,125 @@
+# go-zero缓存设计之业务层缓存
+
+在上一篇[go-zero缓存设计之持久层缓存](redis-cache.md)介绍了db层缓存，回顾一下，db层缓存主要设计可以总结为：
+
+* 缓存只删除不更新
+* 行记录始终只存储一份，即主键对应行记录
+* 唯一索引仅缓存主键值，不直接缓存行记录（参考mysql索引思想）
+* 防缓存穿透设计，默认一分钟
+* 不缓存多行记录
+
+## 前言
+
+在大型业务系统中，通过对持久层添加缓存，对于大多数单行记录查询，相信缓存能够帮持久层减轻很大的访问压力，但在实际业务中，数据读取不仅仅只是单行记录，
+面对大量多行记录的查询，这对持久层也会造成不小的访问压力，除此之外，像秒杀系统、选课系统这种高并发的场景，单纯靠持久层的缓存是不现实的，本节我们来 介绍go-zero实践中的缓存设计——biz缓存。
+
+## 适用场景举例
+
+* 选课系统
+* 内容社交系统
+* 秒杀 ...
+
+像这些系统，我们可以在业务层再增加一层缓存来存储系统中的关键信息，如选课系统中学生选课信息，课程剩余名额；内容社交系统中某一段时间之间的内容信息等。
+
+接下来，我们一内容社交系统来进行举例说明。
+
+在内容社交系统中，我们一般是先查询一批内容列表，然后点击某条内容查看详情，
+
+在没有添加biz缓存前，内容信息的查询流程图应该为：
+
+
+
+从图以及上一篇文章[go-zero缓存设计之持久层缓存](redis-cache.md)中我们可以知道，内容列表的获取是没办法依赖缓存的，
+如果我们在业务层添加一层缓存用来存储列表中的关键信息（甚至完整信息），那么多行记录的访问不在是一个问题，这就是biz redis要做的事情。 接下来我们来看一下设计方案，假设内容系统中单行记录包含以下字段
+
+|字段名称|字段类型|备注|
+|---|---|---|
+|id|string|内容id|
+|title|string|标题|
+|content|string|详细内容|
+|createTime|time.Time|创建时间|
+
+我们的目标是获取一批内容列表，而尽量避免内容列表走db造成访问压力，首先我们采用redis的sort set数据结构来存储，根需要存储的字段信息量，有两种redis存储方案：
+
+* 缓存局部信息
+
+ 
+对其关键字段信息（如：id等）按照一定规则压缩，并存储，score我们用`createTime`毫秒值（时间值相等这里不讨论），这种存储方案的好处是节约redis存储空间，
+那另一方面，缺点就是需要对列表详细内容进行二次回查（但这次回查是会利用到持久层的行记录缓存的）
+
+* 缓存完整信息
+
+ 
+对发布的所有内容按照一定规则压缩后均进行存储，同样score我们还是用`createTime`毫秒值，这种存储方案的好处是业务的增、删、查、改均走reids，而db层这时候
+就可以不用考虑行记录缓存了，持久层仅提供数据备份和恢复使用，从另一方面来看，其缺点也很明显，需要的存储空间、配置要求更高，费用也会随之增大。
+
+示例代码：
+```golang
+type Content struct {
+ Id string `json:"id"`
+ Title string `json:"title"`
+ Content string `json:"content"`
+ CreateTime time.Time `json:"create_time"`
+}
+
+const bizContentCacheKey = `biz#content#cache`
+
+// AddContent 提供内容存储
+func AddContent(r redis.Redis, c *Content) error {
+ v := compress(c)
+ _, err := r.Zadd(bizContentCacheKey, c.CreateTime.UnixNano()/1e6, v)
+ return err
+}
+
+// DelContent 提供内容删除
+func DelContent(r redis.Redis, c *Content) error {
+ v := compress(c)
+ _, err := r.Zrem(bizContentCacheKey, v)
+
+ return err
+}
+
+// 内容压缩
+func compress(c *Content) string {
+ // todo: do it yourself
+ var ret string
+ return ret
+}
+
+// 内容解压
+func unCompress(v string) *Content {
+ // todo: do it yourself
+ var ret Content
+ return &ret
+}
+
+// ListByRangeTime提供根据时间段进行数据查询
+func ListByRangeTime(r redis.Redis, start, end time.Time) ([]*Content, error) {
+ kvs, err := r.ZrangebyscoreWithScores(bizContentCacheKey, start.UnixNano()/1e6, end.UnixNano()/1e6)
+ if err != nil {
+ return nil, err
+ }
+
+ var list []*Content
+ for _, kv := range kvs {
+ data:=unCompress(kv.Key)
+ list = append(list, data)
+ }
+
+ return list, nil
+}
+
+```
+
+在以上例子中，redis是没有设置过期时间的，我们将增、删、改、查操作均同步到redis，我们认为内容社交系统的列表访问请求是比较高的情况下才做这样的方案设计，
+除此之外，还有一些数据访问，没有想内容设计系统这么频繁的访问， 可能是某一时间段内访问量突如其来的增加，之后可能很长一段时间才会再访问一次，以此间隔，
+或者说不会再访问了，面对这种场景，如果我又该如何考虑缓存的设计呢？在go-zero内容实践中，有两种方案可以解决这种问题：
+
+* 增加内存缓存：通过内存缓存来存储当前可能突发访问量比较大的数据，常用的存储方案采用map数据结构来存储，map数据存储实现比较简单，但缓存过期处理则需要增加
+ 定时器来出来，另一宗方案是通过go-zero库中的 [Cache](https://github.com/zeromicro/go-zero/blob/master/core/collection/cache.go) ，其是专门
+ 用于内存管理.
+* 采用biz redis,并设置合理的过期时间
+
+# 总结
+以上两个场景可以包含大部分的多行记录缓存，对于多行记录查询量不大的场景，暂时没必要直接把biz redis放进去，可以先尝试让db来承担，开发人员可以根据持久层监控及服务
+监控来衡量时候需要引入biz。
diff --git a/go-zero.dev/cn/business-coding.md b/go-zero.dev/cn/business-coding.md
new file mode 100644
index 00000000..66ff45c6
--- /dev/null
+++ b/go-zero.dev/cn/business-coding.md
@@ -0,0 +1,124 @@
+# 业务编码
+前面一节，我们已经根据初步需求编写了user.api来描述user服务对外提供哪些服务访问，在本节我们接着前面的步伐，
+通过业务编码来讲述go-zero怎么在实际业务中使用。
+
+## 添加Mysql配置
+```shell
+$ vim service/user/cmd/api/internal/config/config.go
+```
+```go
+package config
+
+import "github.com/tal-tech/go-zero/rest"
+
+type Config struct {
+ rest.RestConf
+ Mysql struct{
+ DataSource string
+ }
+
+ CacheRedis cache.CacheConf
+}
+```
+
+## 完善yaml配置
+```shell
+$ vim service/user/cmd/api/etc/user-api.yaml
+```
+```yaml
+Name: user-api
+Host: 0.0.0.0
+Port: 8888
+Mysql:
+ DataSource: $user:$password@tcp($url)/$db?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+CacheRedis:
+ - Host: $host
+ Pass: $pass
+ Type: node
+```
+
+> [!TIP]
+> $user: mysql数据库user
+>
+> $password: mysql数据库密码
+>
+> $url: mysql数据库连接地址
+>
+> $db: mysql数据库db名称，即user表所在database
+>
+> $host: redis连接地址 格式：ip:port，如:127.0.0.1:6379
+>
+> $pass: redis密码
+>
+> 更多配置信息，请参考[api配置介绍](api-config.md)
+
+## 完善服务依赖
+```shell
+$ vim service/user/cmd/api/internal/svc/servicecontext.go
+```
+```go
+type ServiceContext struct {
+ Config config.Config
+ UserModel model.UserModel
+}
+
+func NewServiceContext(c config.Config) *ServiceContext {
+ conn:=sqlx.NewMysql(c.Mysql.DataSource)
+ return &ServiceContext{
+ Config: c,
+ UserModel: model.NewUserModel(conn,c.CacheRedis),
+ }
+}
+```
+## 填充登录逻辑
+```shell
+$ vim service/user/cmd/api/internal/logic/loginlogic.go
+```
+
+```go
+func (l *LoginLogic) Login(req types.LoginReq) (*types.LoginReply, error) {
+ if len(strings.TrimSpace(req.Username)) == 0 || len(strings.TrimSpace(req.Password)) == 0 {
+ return nil, errors.New("参数错误")
+ }
+
+ userInfo, err := l.svcCtx.UserModel.FindOneByNumber(req.Username)
+ switch err {
+ case nil:
+ case model.ErrNotFound:
+ return nil, errors.New("用户名不存在")
+ default:
+ return nil, err
+ }
+
+ if userInfo.Password != req.Password {
+ return nil, errors.New("用户密码不正确")
+ }
+
+ // ---start---
+ now := time.Now().Unix()
+ accessExpire := l.svcCtx.Config.Auth.AccessExpire
+ jwtToken, err := l.getJwtToken(l.svcCtx.Config.Auth.AccessSecret, now, l.svcCtx.Config.Auth.AccessExpire, userInfo.Id)
+ if err != nil {
+ return nil, err
+ }
+ // ---end---
+
+ return &types.LoginReply{
+ Id: userInfo.Id,
+ Name: userInfo.Name,
+ Gender: userInfo.Gender,
+ AccessToken: jwtToken,
+ AccessExpire: now + accessExpire,
+ RefreshAfter: now + accessExpire/2,
+ }, nil
+}
+```
+> [!TIP]
+> 上述代码中 [start]-[end]的代码实现见[jwt鉴权](jwt.md)章节
+
+# 猜你想看
+* [api语法](api-grammar.md)
+* [goctl api命令](goctl-api.md)
+* [api目录结构介绍](api-dir.md)
+* [jwt鉴权](jwt.md)
+* [api配置介绍](api-config.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/business-dev.md b/go-zero.dev/cn/business-dev.md
new file mode 100644
index 00000000..ce273c7a
--- /dev/null
+++ b/go-zero.dev/cn/business-dev.md
@@ -0,0 +1,59 @@
+# 业务开发
+本章节我们用一个简单的示例去演示一下go-zero中的一些基本功能。本节将包含以下小节：
+* [目录拆分](service-design.md)
+* [model生成](model-gen.md)
+* [api文件编写](api-coding.md)
+* [业务编码](business-coding.md)
+* [jwt鉴权](jwt.md)
+* [中间件使用](middleware.md)
+* [rpc服务编写与调用](rpc-call.md)
+* [错误处理](error-handle.md)
+
+## 演示工程下载
+在正式进入后续文档叙述前，可以先留意一下这里的源码，后续我们会基于这份源码进行功能的递进式演示，
+而不是完全从0开始，如果你从[快速入门](quick-start.md)章节过来，这份源码结构对你来说不是问题。
+
+点击
](https://github.com/zeromicro/go-zero)
+[
](https://github.com/zeromicro/goctl-intellij/blob/main/LICENSE)
+[
](https://github.com/zeromicro/goctl-intellij/releases)
+[
](https://github.com/zeromicro/goctl-intellij/actions)
+
+## 介绍
+一款支持go-zero api语言结构语法高亮、检测以及api、rpc、model快捷生成的插件工具。
+
+
+## idea版本要求
+* IntelliJ 2019.3+ (Ultimate or Community)
+* Goland 2019.3+
+* WebStorm 2019.3+
+* PhpStorm 2019.3+
+* PyCharm 2019.3+
+* RubyMine 2019.3+
+* CLion 2019.3+
+
+## 版本特性
+* api语法高亮
+* api语法、语义检测
+* struct、route、handler重复定义检测
+* type跳转到类型声明位置
+* 上下文菜单中支持api、rpc、mode相关menu选项
+* 代码格式化(option+command+L)
+* 代码提示
+
+## 安装方式
+
+### 方式一
+在github的release中找到最新的zip包，下载本地安装即可。（无需解压）
+
+### 方式二
+在plugin商店中，搜索`Goctl`安装即可
+
+
+## 预览
+
+
+## 新建 Api(Proto) file
+在工程区域目标文件夹`右键->New-> New Api(Proto) File ->Empty File/Api(Proto) Template`,如图：
+
+
+# 快速生成api/rpc服务
+在目标文件夹`右键->New->Go Zero -> Api Greet Service/Rpc Greet Service`
+
+
+
+# Api/Rpc/Model Code生成
+
+## 方法一(工程区域)
+
+对应文件（api、proto、sql）`右键->New->Go Zero-> Api/Rpc/Model Code`,如图：
+
+
+
+## 方法二（编辑区域）
+对应文件（api、proto、sql）`右键-> Generate-> Api/Rpc/Model Code`
+
+
+# 错误提示
+
+
+
+# Live Template
+Live Template可以加快我们对api文件的编写，比如我们在go文件中输入`main`关键字根据tip回车后会插入一段模板代码
+```go
+func main(){
+
+}
+```
+或者说看到下图你会更加熟悉，曾几何时你还在这里定义过template
+
+
+下面就进入今天api语法中的模板使用说明吧，我们先来看看service模板的效果
+
+
+首先上一张图了解一下api文件中几个模板生效区域（psiTree元素区域）
+
+
+#### 预设模板及生效区域
+| 模板关键字 | psiTree生效区域 |描述
+| ---- | ---- | ---- |
+| @doc | ApiService |doc注释模板|
+| doc | ApiService |doc注释模板|
+| struct | Struct |struct声明模板|
+| info | ApiFile |info block模板|
+| type | ApiFile |type group模板|
+| handler | ApiService |handler文件名模板|
+| get | ApiService |get方法路由模板|
+| head | ApiService |head方法路由模板|
+| post | ApiService |post方法路由模板|
+| put | ApiService |put方法路由模板|
+| delete | ApiService |delete方法路由模板|
+| connect | ApiService |connect方法路由模板|
+| options | ApiService |options方法路由模板|
+| trace | ApiService |trace方法路由模板|
+| service | ApiFile |service服务block模板|
+| json | Tag、Tag literal |tag模板|
+| xml | Tag、Tag literal |tag模板|
+| path | Tag、Tag literal |tag模板|
+| form | Tag、Tag literal |tag模板|
+
+关于每个模板对应内容可在`Goland(mac Os)->Preference->Editor->Live Templates-> Api|Api Tags`中查看详细模板内容，如json tag模板内容为
+```go
+json:"$FIELD_NAME$"
+```
+
+
+
diff --git a/go-zero.dev/cn/join-us.md b/go-zero.dev/cn/join-us.md
new file mode 100644
index 00000000..acebb0da
--- /dev/null
+++ b/go-zero.dev/cn/join-us.md
@@ -0,0 +1,53 @@
+# 加入我们
+
+## 概要
+
+
+[go-zero](https://github.com/zeromicro/go-zero) 是一个基于[MIT License](https://github.com/zeromicro/go-zero/blob/master/LICENSE) 的开源项目，大家在使用中发现bug，有新的特性等，均可以参与到go-zero的贡献中来，我们非常欢迎大家的积极参与，也会最快响应大家提出的各种问题，pr等。
+
+## 贡献形式
+* [Pull Request](https://github.com/zeromicro/go-zero/pulls)
+* [Issue](https://github.com/zeromicro/go-zero/issues)
+
+## 贡献须知
+go-zero 的Pull request中的代码需要满足一定规范
+* 命名规范，请阅读[命名规范](naming-spec.md)
+* 以英文注释为主
+* pr时备注好功能特性，描述需要清晰，简洁
+* 增加单元测试覆盖率达80%+
+
+## 贡献代码（pr）
+* 进入[go-zero](https://github.com/zeromicro/go-zero) 项目，fork一份[go-zero](https://github.com/zeromicro/go-zero) 项目到自己的github仓库中。
+* 回到自己的github主页，找到`xx/go-zero`项目，其中xx为你的用户名，如`anqiansong/go-zero`
+
+ 
+* 克隆代码到本地
+
+ 
+* 开发代码，push到自己的github仓库
+* 进入自己的github中go-zero项目，点击浮层上的的`【Pull requests】`进入Compare页面。
+
+ 
+
+* `base repository`选择`tal-tech/go-zero` `base:master`,`head repository`选择`xx/go-zero` `compare:$branch` ，`$branch`为你开发的分支，如图：
+
+ 
+
+* 点击`【Create pull request】`即可实现pr申请
+* 确认pr是否提交成功，进入[go-zero](https://github.com/zeromicro/go-zero) 的[Pull requests](https://github.com/zeromicro/go-zero/pulls) 查看，应该有自己提交的记录，名称为你的开发时的分支名称
+
+ 
+
+## Issue
+在我们的社区中，有很多伙伴会积极的反馈一些go-zero使用过程中遇到的问题，由于社区人数较多，我们虽然会实时的关注社区动态，但大家问题反馈过来都是随机的，当我们团队还在解决某一个伙伴提出的问题时，另外的问题也反馈上来，可能会导致团队会很容易忽略掉，为了能够一一的解决大家的问题，我们强烈建议大家通过issue的方式来反馈问题，包括但不限于bug，期望的新功能特性等，我们在实现某一个新特性时也会在issue中体现，大家在这里也能够在这里获取到go-zero的最新动向，也欢迎大家来积极的参与讨论。
+
+### 怎么提Issue
+* 点击[这里](https://github.com/zeromicro/go-zero/issues) 进入go-zero的Issue页面或者直接访问[https://github.com/zeromicro/go-zero/issues](https://github.com/zeromicro/go-zero/issues) 地址
+* 点击右上角的`【New issue】`新建issue
+* 填写issue标题和内容
+* 点击`【Submit new issue】`提交issue
+
+
+## 参考文档
+
+* [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)
\ No newline at end of file
diff --git a/go-zero.dev/cn/jwt.md b/go-zero.dev/cn/jwt.md
new file mode 100644
index 00000000..cdb20a01
--- /dev/null
+++ b/go-zero.dev/cn/jwt.md
@@ -0,0 +1,238 @@
+# jwt鉴权
+
+## 概述
+> JSON Web令牌（JWT）是一个开放标准（RFC 7519），它定义了一种紧凑而独立的方法，用于在各方之间安全地将信息作为JSON对象传输。由于此信息是经过数字签名的，因此可以被验证和信任。可以使用秘密（使用HMAC算法）或使用RSA或ECDSA的公钥/私钥对对JWT进行签名。
+
+## 什么时候应该使用JWT
+* 授权：这是使用JWT的最常见方案。一旦用户登录，每个后续请求将包括JWT，从而允许用户访问该令牌允许的路由，服务和资源。单一登录是当今广泛使用JWT的一项功能，因为它的开销很小并且可以在不同的域中轻松使用。
+
+* 信息交换：JSON Web令牌是在各方之间安全地传输信息的一种好方法。因为可以对JWT进行签名（例如，使用公钥/私钥对），所以您可以确保发件人是他们所说的人。此外，由于签名是使用标头和有效负载计算的，因此您还可以验证内容是否未被篡改。
+
+## 为什么要使用JSON Web令牌
+由于JSON不如XML冗长，因此在编码时JSON的大小也较小，从而使JWT比SAML更为紧凑。这使得JWT是在HTML和HTTP环境中传递的不错的选择。
+
+在安全方面，只能使用HMAC算法由共享机密对SWT进行对称签名。但是，JWT和SAML令牌可以使用X.509证书形式的公用/专用密钥对进行签名。与签署JSON的简单性相比，使用XML Digital Signature签署XML而不引入模糊的安全漏洞是非常困难的。
+
+JSON解析器在大多数编程语言中都很常见，因为它们直接映射到对象。相反，XML没有自然的文档到对象的映射。与SAML断言相比，这使使用JWT更加容易。
+
+关于用法，JWT是在Internet规模上使用的。这突显了在多个平台（尤其是移动平台）上对JSON Web令牌进行客户端处理的简便性。
+
+> [!TIP]
+> 以上内容全部来自[jwt官网介绍](https://jwt.io/introduction)
+
+## go-zero中怎么使用jwt
+jwt鉴权一般在api层使用，我们这次演示工程中分别在user api登录时生成jwt token，在search api查询图书时验证用户jwt token两步来实现。
+
+### user api生成jwt token
+接着[业务编码](business-coding.md)章节的内容，我们完善上一节遗留的`getJwtToken`方法，即生成jwt token逻辑
+
+#### 添加配置定义和yaml配置项
+```shell
+$ vim service/user/cmd/api/internal/config/config.go
+```
+```go
+type Config struct {
+ rest.RestConf
+ Mysql struct{
+ DataSource string
+ }
+ CacheRedis cache.CacheConf
+ Auth struct {
+ AccessSecret string
+ AccessExpire int64
+ }
+}
+```
+```shell
+$ vim service/user/cmd/api/etc/user-api.yaml
+```
+```yaml
+Name: user-api
+Host: 0.0.0.0
+Port: 8888
+Mysql:
+ DataSource: $user:$password@tcp($url)/$db?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+CacheRedis:
+ - Host: $host
+ Pass: $pass
+ Type: node
+Auth:
+ AccessSecret: $AccessSecret
+ AccessExpire: $AccessExpire
+```
+
+> [!TIP]
+> $AccessSecret：生成jwt token的密钥，最简单的方式可以使用一个uuid值。
+>
+> $AccessExpire：jwt token有效期，单位：秒
+>
+> 更多配置信息，请参考[api配置介绍](api-config.md)
+
+```shell
+$ vim service/user/cmd/api/internal/logic/loginlogic.go
+```
+
+```go
+func (l *LoginLogic) getJwtToken(secretKey string, iat, seconds, userId int64) (string, error) {
+ claims := make(jwt.MapClaims)
+ claims["exp"] = iat + seconds
+ claims["iat"] = iat
+ claims["userId"] = userId
+ token := jwt.New(jwt.SigningMethodHS256)
+ token.Claims = claims
+ return token.SignedString([]byte(secretKey))
+}
+```
+
+### search api使用jwt token鉴权
+#### 编写search.api文件
+```shell
+$ vim service/search/cmd/api/search.api
+```
+```text
+type (
+ SearchReq {
+ // 图书名称
+ Name string `form:"name"`
+ }
+
+ SearchReply {
+ Name string `json:"name"`
+ Count int `json:"count"`
+ }
+)
+
+@server(
+ jwt: Auth
+)
+service search-api {
+ @handler search
+ get /search/do (SearchReq) returns (SearchReply)
+}
+
+service search-api {
+ @handler ping
+ get /search/ping
+}
+```
+
+> [!TIP]
+> `jwt: Auth`：开启jwt鉴权
+>
+> 如果路由需要jwt鉴权，则需要在service上方声明此语法标志，如上文中的` /search/do`
+>
+> 不需要jwt鉴权的路由就无需声明，如上文中`/search/ping`
+>
+> 更多语法请阅读[api语法介绍](api-grammar.md)
+
+
+#### 生成代码
+前面已经描述过有三种方式去生成代码，这里就不赘述了。
+
+
+#### 添加yaml配置项
+```shell
+$ vim service/search/cmd/api/etc/search-api.yaml
+```
+```yaml
+Name: search-api
+Host: 0.0.0.0
+Port: 8889
+Auth:
+ AccessSecret: $AccessSecret
+ AccessExpire: $AccessExpire
+
+```
+
+> [!TIP]
+> $AccessSecret：这个值必须要和user api中声明的一致。
+>
+> $AccessExpire: 有效期
+>
+> 这里修改一下端口，避免和user api端口8888冲突
+
+### 验证 jwt token
+* 启动user api服务，登录
+ ```shell
+ $ cd service/user/cmd/api
+ $ go run user.go -f etc/user-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+ ```shell
+ $ curl -i -X POST \
+ http://127.0.0.1:8888/user/login \
+ -H 'content-type: application/json' \
+ -d '{
+ "username":"666",
+ "password":"123456"
+ }'
+ ```
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Mon, 08 Feb 2021 10:37:54 GMT
+ Content-Length: 251
+
+ {"id":1,"name":"小明","gender":"男","accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NjcwNzQsImlhdCI6MTYxMjc4MDY3NCwidXNlcklkIjoxfQ.JKa83g9BlEW84IiCXFGwP2aSd0xF3tMnxrOzVebbt80","accessExpire":1612867074,"refreshAfter":1612823874}
+ ```
+* 启动search api服务，调用`/search/do`验证jwt鉴权是否通过
+ ```shell
+ $ go run search.go -f etc/search-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8889...
+ ```
+ 我们先不传jwt token，看看结果
+ ```shell
+ $ curl -i -X GET \
+ 'http://127.0.0.1:8889/search/do?name=%E8%A5%BF%E6%B8%B8%E8%AE%B0'
+ ```
+ ```text
+ HTTP/1.1 401 Unauthorized
+ Date: Mon, 08 Feb 2021 10:41:57 GMT
+ Content-Length: 0
+ ```
+ 很明显，jwt鉴权失败了，返回401的statusCode，接下来我们带一下jwt token（即用户登录返回的`accessToken`）
+ ```shell
+ $ curl -i -X GET \
+ 'http://127.0.0.1:8889/search/do?name=%E8%A5%BF%E6%B8%B8%E8%AE%B0' \
+ -H 'authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NjcwNzQsImlhdCI6MTYxMjc4MDY3NCwidXNlcklkIjoxfQ.JKa83g9BlEW84IiCXFGwP2aSd0xF3tMnxrOzVebbt80'
+ ```
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Mon, 08 Feb 2021 10:44:45 GMT
+ Content-Length: 21
+
+ {"name":"","count":0}
+ ```
+
+ > [!TIP]
+ > 服务启动错误，请查看[常见错误处理](error.md)
+
+
+至此，jwt从生成到使用就演示完成了，jwt token的鉴权是go-zero内部已经封装了，你只需在api文件中定义服务时简单的声明一下即可。
+
+### 获取jwt token中携带的信息
+go-zero从jwt token解析后会将用户生成token时传入的kv原封不动的放在http.Request的Context中，因此我们可以通过Context就可以拿到你想要的值
+```shell
+$ vim /service/search/cmd/api/internal/logic/searchlogic.go
+```
+添加一个log来输出从jwt解析出来的userId。
+```go
+func (l *SearchLogic) Search(req types.SearchReq) (*types.SearchReply, error) {
+ logx.Infof("userId: %v",l.ctx.Value("userId"))// 这里的key和生成jwt token时传入的key一致
+ return &types.SearchReply{}, nil
+}
+```
+运行结果
+```text
+{"@timestamp":"2021-02-09T10:29:09.399+08","level":"info","content":"userId: 1"}
+```
+
+# 猜你想看
+* [jwt介绍](https://jwt.io/)
+* [api配置介绍](api-config.md)
+* [api语法](api-grammar.md)
diff --git a/doc/keywords.md b/go-zero.dev/cn/keywords.md
similarity index 100%
rename from doc/keywords.md
rename to go-zero.dev/cn/keywords.md
diff --git a/go-zero.dev/cn/learning-resource.md b/go-zero.dev/cn/learning-resource.md
new file mode 100644
index 00000000..1bd06759
--- /dev/null
+++ b/go-zero.dev/cn/learning-resource.md
@@ -0,0 +1,5 @@
+# 学习资源
+这里将不定期更新go-zero的最新学习资源通道，目前包含通道有：
+* [公众号](wechat.md)
+* [Go夜读](goreading.md)
+* [Go开源说](gotalk.md)
\ No newline at end of file
diff --git a/doc/loadshedding.md b/go-zero.dev/cn/loadshedding.md
similarity index 100%
rename from doc/loadshedding.md
rename to go-zero.dev/cn/loadshedding.md
diff --git a/go-zero.dev/cn/log-collection.md b/go-zero.dev/cn/log-collection.md
new file mode 100644
index 00000000..f5271947
--- /dev/null
+++ b/go-zero.dev/cn/log-collection.md
@@ -0,0 +1,139 @@
+# 日志收集
+为了保证业务稳定运行，预测服务不健康风险，日志的收集可以帮助我们很好的观察当前服务的健康状况，
+在传统业务开发中，机器部署还不是很多时，我们一般都是直接登录服务器进行日志查看、调试，但随着业务的增大，服务的不断拆分，
+服务的维护成本也会随之变得越来越复杂，在分布式系统中，服务器机子增多，服务分布在不同的服务器上，当遇到问题时，
+我们不能使用传统做法，登录到服务器进行日志排查和调试，这个复杂度可想而知。
+
+
+> [!TIP]
+> 如果是一个简单的单体服务系统或者服务过于小不建议直接使用，否则会适得其反。
+
+## 准备工作
+* kafka
+* elasticsearch
+* kibana
+* filebeat、Log-Pilot（k8s）
+* go-stash
+
+## filebeat配置
+```shell
+$ vim xx/filebeat.yaml
+```
+
+```yaml
+filebeat.inputs:
+- type: log
+ enabled: true
+ # 开启json解析
+ json.keys_under_root: true
+ json.add_error_key: true
+ # 日志文件路径
+ paths:
+ - /var/log/order/*.log
+
+setup.template.settings:
+ index.number_of_shards: 1
+
+# 定义kafka topic field
+fields:
+ log_topic: log-collection
+
+# 输出到kafka
+output.kafka:
+ hosts: ["127.0.0.1:9092"]
+ topic: '%{[fields.log_topic]}'
+ partition.round_robin:
+ reachable_only: false
+ required_acks: 1
+ keep_alive: 10s
+
+# ================================= Processors =================================
+processors:
+ - decode_json_fields:
+ fields: ['@timestamp','level','content','trace','span','duration']
+ target: ""
+```
+
+> [!TIP]
+> xx为filebeat.yaml所在路径
+
+## go-stash配置
+* 新建`config.yaml`文件
+* 添加配置内容
+
+```shell
+$ vim config.yaml
+```
+
+```yaml
+Clusters:
+- Input:
+ Kafka:
+ Name: go-stash
+ Log:
+ Mode: file
+ Brokers:
+ - "127.0.0.1:9092"
+ Topics:
+ - log-collection
+ Group: stash
+ Conns: 3
+ Consumers: 10
+ Processors: 60
+ MinBytes: 1048576
+ MaxBytes: 10485760
+ Offset: first
+ Filters:
+ - Action: drop
+ Conditions:
+ - Key: status
+ Value: "503"
+ Type: contains
+ - Key: type
+ Value: "app"
+ Type: match
+ Op: and
+ - Action: remove_field
+ Fields:
+ - source
+ - _score
+ - "@metadata"
+ - agent
+ - ecs
+ - input
+ - log
+ - fields
+ Output:
+ ElasticSearch:
+ Hosts:
+ - "http://127.0.0.1:9200"
+ Index: "go-stash-{{yyyy.MM.dd}}"
+ MaxChunkBytes: 5242880
+ GracePeriod: 10s
+ Compress: false
+ TimeZone: UTC
+```
+
+## 启动服务(按顺序启动)
+* 启动kafka
+* 启动elasticsearch
+* 启动kibana
+* 启动go-stash
+* 启动filebeat
+* 启动order-api服务及其依赖服务（go-zero-demo工程中的order-api服务）
+
+## 访问kibana
+进入127.0.0.1:5601
+
+
+> [!TIP]
+> 这里仅演示收集服务中通过logx产生的日志，nginx中日志收集同理。
+
+
+# 参考文档
+* [kafka](http://kafka.apache.org/)
+* [elasticsearch](https://www.elastic.co/cn/elasticsearch/)
+* [kibana](https://www.elastic.co/cn/kibana)
+* [filebeat](https://www.elastic.co/cn/beats/filebeat)
+* [go-stash](https://github.com/tal-tech/go-stash)
+* [filebeat配置](https://www.elastic.co/guide/en/beats/filebeat/current/index.html)
diff --git a/go-zero.dev/cn/logx.md b/go-zero.dev/cn/logx.md
new file mode 100644
index 00000000..dff24e38
--- /dev/null
+++ b/go-zero.dev/cn/logx.md
@@ -0,0 +1,185 @@
+# logx
+
+
+## 使用示例
+
+```go
+var c logx.LogConf
+// 从 yaml 文件中 初始化配置
+conf.MustLoad("config.yaml", &c)
+
+// logx 根据配置初始化
+logx.MustSetup(c)
+
+logx.Info("This is info!")
+logx.Infof("This is %s!", "info")
+
+logx.Error("This is error!")
+logx.Errorf("this is %s!", "error")
+
+logx.Close()
+```
+
+## 初始化
+logx 有很多可以配置项，可以参考 logx.LogConf 中的定义。目前可以使用
+
+```go
+logx.MustSetUp(c)
+```
+进行初始化配置，如果没有进行初始化配置，所有的配置将使用默认配置。
+
+## Level
+logx 支持的打印日志级别有：
+- info
+- error
+- server
+- fatal
+- slow
+- stat
+
+可以使用对应的方法打印出对应级别的日志。
+同时为了方便调试，线上使用，可以动态调整日志打印级别，其中可以通过 **logx.SetLevel(uint32)** 进行级别设置，也可以通过配置初始化进行设置。目前支持的参数为：
+
+```go
+const (
+ // 打印所有级别的日志
+ InfoLevel = iotas
+ // 打印 errors, slows, stacks 日志
+ ErrorLevel
+ // 仅打印 server 级别日志
+ SevereLevel
+)
+```
+
+## 日志模式
+目前日志打印模式主要分为2种，一种文件输出，一种控制台输出。推荐方式，当采用 k8s，docker 等部署方式的时候，可以将日志输出到控制台，使用日志收集器收集导入至 es 进行日志分析。如果是直接部署方式，可以采用文件输出方式，logx 会自动在指定文件目录创建对应 5 个对应级别的的日志文件保存日志。
+
+```bash
+.
+├── access.log
+├── error.log
+├── severe.log
+├── slow.log
+└── stat.log
+```
+
+同时会按照自然日进行文件分割，当超过指定配置天数，会对日志文件进行自动删除，打包等操作。
+
+## 禁用日志
+如果不需要日志打印，可以使用 **logx.Close()** 关闭日志输出。注意，当禁用日志输出，将无法在次打开，具体可以参考 **logx.RotateLogger** 和 **logx.DailyRotateRule** 的实现。
+
+## 关闭日志
+因为 logx 采用异步进行日志输出，如果没有正常关闭日志，可能会造成部分日志丢失的情况。必须在程序退出的地方关闭日志输出：
+```go
+logx.Close()
+```
+框架中 rest 和 zrpc 等大部分地方已经做好了日志配置和关闭相关操作，用户可以不用关心。
+同时注意，当关闭日志输出之后，将无法在次打印日志了。
+
+推荐写法：
+```go
+import "github.com/tal-tech/go-zero/core/proc"
+
+// grace close log
+proc.AddShutdownListener(func() {
+ logx.Close()
+})
+```
+
+## Duration
+我们打印日志的时候可能需要打印耗时情况，可以使用 **logx.WithDuration(time.Duration)**, 参考如下示例：
+
+```go
+startTime := timex.Now()
+// 数据库查询
+rows, err := conn.Query(q, args...)
+duration := timex.Since(startTime)
+if duration > slowThreshold {
+ logx.WithDuration(duration).Slowf("[SQL] query: slowcall - %s", stmt)
+} else {
+ logx.WithDuration(duration).Infof("sql query: %s", stmt)
+}
+```
+
+
+会输出如下格式
+
+```json
+{"@timestamp":"2020-09-12T01:22:55.552+08","level":"info","duration":"3.0ms","content":"sql query:..."}
+{"@timestamp":"2020-09-12T01:22:55.552+08","level":"slow","duration":"500ms","content":"[SQL] query: slowcall - ..."}
+```
+
+这样就可以很容易统计出慢 sql 相关信息。
+
+## TraceLog
+tracingEntry 是为了链路追踪日志输出定制的。可以打印 context 中的 traceId 和 spanId 信息，配合我们的 **rest** 和 **zrpc** 很容易完成链路日志的相关打印。示例如下
+
+```go
+logx.WithContext(context.Context).Info("This is info!")
+```
+
+
+## SysLog
+
+应用中可能有部分采用系统 log 进行日志打印，logx 同样封装方法，很容易将 log 相关的日志收集到 logx 中来。
+
+```go
+logx.CollectSysLog()
+```
+
+
+
+
+# 日志配置相关
+**LogConf** 定义日志系统所需的基本配置
+
+完整定义如下：
+
+```go
+type LogConf struct {
+ ServiceName string `json:",optional"`
+ Mode string `json:",default=console,options=console|file|volume"`
+ Path string `json:",default=logs"`
+ Level string `json:",default=info,options=info|error|severe"`
+ Compress bool `json:",optional"`
+ KeepDays int `json:",optional"`
+ StackCooldownMillis int `json:",default=100"`
+}
+```
+
+
+## Mode
+**Mode** 定义了日志打印的方式。默认的模式是 **console**， 打印到控制台上面。
+
+目前支持的模式如下：
+
+- console
+ - 打印到控制台
+- file
+ - 打印到指定路径下的access.log, error.log, stat.log等文件里
+- volume
+ - 为了在k8s内打印到mount进来的存储上，因为多个pod可能会覆盖相同的文件，volume模式自动识别pod并按照pod分开写各自的日志文件
+
+## Path
+**Path** 定义了文件日志的输出路径，默认值为 **logs**。
+
+## Level
+**Level** 定义了日志打印级别，默认值为 **info**。
+目前支持的级别如下:
+
+- info
+- error
+- severe
+
+
+
+## Compress
+**Compress** 定义了日志是否需要压缩，默认值为 **false**。在 Mode 为 file 模式下面，文件最后会进行打包压缩成 .gz 文件。
+
+
+## KeepDays
+**KeepDays** 定义日志最大保留天数，默认值为 0，表示不会删除旧的日志。在 Mode 为 file 模式下面，如果超过了最大保留天数，旧的日志文件将会被删除。
+
+
+## StackCooldownMillis
+**StackCooldownMillis** 定义了日志输出间隔，默认为 100 毫秒。
diff --git a/doc/mapping.md b/go-zero.dev/cn/mapping.md
similarity index 96%
rename from doc/mapping.md
rename to go-zero.dev/cn/mapping.md
index 9e49340f..6aafa233 100644
--- a/doc/mapping.md
+++ b/go-zero.dev/cn/mapping.md
@@ -112,7 +112,7 @@ service user {
* `sex`：必填，取值为`male`或`female`
* `avatar`：选填，默认为`default.png`
-更多详情参见[unmarshaler_test.go](https://github.com/tal-tech/go-zero/blob/master/core/mapping/unmarshaler_test.go)
+更多详情参见[unmarshaler_test.go](https://github.com/zeromicro/go-zero/blob/master/core/mapping/unmarshaler_test.go)
## 2. http api返回体的序列化
diff --git a/doc/mapreduce.md b/go-zero.dev/cn/mapreduce.md
similarity index 95%
rename from doc/mapreduce.md
rename to go-zero.dev/cn/mapreduce.md
index c87523f4..374e0a02 100644
--- a/doc/mapreduce.md
+++ b/go-zero.dev/cn/mapreduce.md
@@ -4,13 +4,13 @@
那么通过什么手段来优化呢？我们首先想到的是通过并发来的方式来处理依赖，这样就能降低整个依赖的耗时，Go基础库中为我们提供了 [WaitGroup](https://golang.org/pkg/sync/#WaitGroup) 工具用来进行并发控制，但实际业务场景中多个依赖如果有一个出错我们期望能立即返回而不是等所有依赖都执行完再返回结果，而且WaitGroup中对变量的赋值往往需要加锁，每个依赖函数都需要添加Add和Done对于新手来说比较容易出错
-基于以上的背景，go-zero框架中为我们提供了并发处理工具[MapReduce](https://github.com/tal-tech/go-zero/blob/master/core/mr/mapreduce.go)，该工具开箱即用，不需要做什么初始化，我们通过下图看下使用MapReduce和没使用的耗时对比:
+基于以上的背景，go-zero框架中为我们提供了并发处理工具[MapReduce](https://github.com/zeromicro/go-zero/blob/master/core/mr/mapreduce.go)，该工具开箱即用，不需要做什么初始化，我们通过下图看下使用MapReduce和没使用的耗时对比:
相同的依赖，串行处理的话需要200ms，使用MapReduce后的耗时等于所有依赖中最大的耗时为100ms，可见MapReduce可以大大降低服务耗时，而且随着依赖的增加效果就会越明显，减少处理耗时的同时并不会增加服务器压力
-## 并发处理工具[MapReduce](https://github.com/tal-tech/go-zero/tree/master/core/mr)
+## 并发处理工具[MapReduce](https://github.com/zeromicro/go-zero/tree/master/core/mr)
[MapReduce](https://zh.wikipedia.org/wiki/MapReduce)是Google提出的一个软件架构，用于大规模数据集的并行运算，go-zero中的MapReduce工具正是借鉴了这种架构思想
diff --git a/doc/metric.md b/go-zero.dev/cn/metric.md
similarity index 95%
rename from doc/metric.md
rename to go-zero.dev/cn/metric.md
index 63cd35e5..7bb861d8 100644
--- a/doc/metric.md
+++ b/go-zero.dev/cn/metric.md
@@ -14,7 +14,7 @@ Prometheus Server直接从监控目标中或者间接通过推送网关来拉取
## go-zero基于prometheus的服务指标监控
-[go-zero](https://github.com/tal-tech/go-zero) 框架中集成了基于prometheus的服务指标监控，下面我们通过go-zero官方的示例[shorturl](https://github.com/tal-tech/go-zero/blob/master/doc/shorturl.md)来演示是如何对服务指标进行收集监控的：
+[go-zero](https://github.com/zeromicro/go-zero) 框架中集成了基于prometheus的服务指标监控，下面我们通过go-zero官方的示例[shorturl](https://github.com/zeromicro/go-zero/blob/master/doc/shorturl.md)来演示是如何对服务指标进行收集监控的：
- 第一步需要先安装Prometheus，安装步骤请参考[官方文档](https://prometheus.io/)
- go-zero默认不开启prometheus监控，开启方式很简单，只需要在shorturl-api.yaml文件中增加配置如下，其中Host为Prometheus Server地址为必填配置，Port端口不填默认9091，Path为用来拉取指标的路径默认为/metrics
diff --git a/go-zero.dev/cn/micro-service.md b/go-zero.dev/cn/micro-service.md
new file mode 100644
index 00000000..03ee4a65
--- /dev/null
+++ b/go-zero.dev/cn/micro-service.md
@@ -0,0 +1,309 @@
+# 微服务
+
+在上一篇我们已经演示了怎样快速创建一个单体服务，接下来我们来演示一下如何快速创建微服务，
+在本小节中，api部分其实和单体服务的创建逻辑是一样的，只是在单体服务中没有服务间的通讯而已，
+且微服务中api服务会多一些rpc调用的配置。
+
+## 前言
+本小节将以一个`订单服务`调用`用户服务`来简单演示一下，演示代码仅传递思路，其中有些环节不会一一列举。
+
+## 情景提要
+假设我们在开发一个商城项目，而开发者小明负责用户模块(user)和订单模块(order)的开发，我们姑且将这两个模块拆分成两个微服务①
+
+> [!NOTE]
+> ①：微服务的拆分也是一门学问，这里我们就不讨论怎么去拆分微服务的细节了。
+
+## 演示功能目标
+* 订单服务(order)提供一个查询接口
+* 用户服务(user)提供一个方法供订单服务获取用户信息
+
+## 服务设计分析
+根据情景提要我们可以得知，订单是直接面向用户，通过http协议访问数据，而订单内部需要获取用户的一些基础数据，既然我们的服务是采用微服务的架构设计，
+那么两个服务（user,order）就必须要进行数据交换，服务间的数据交换即服务间的通讯，到了这里，采用合理的通讯协议也是一个开发人员需要
+考虑的事情，可以通过http，rpc等方式来进行通讯，这里我们选择rpc来实现服务间的通讯，相信这里我已经对"rpc服务存在有什么作用？"已经作了一个比较好的场景描述。
+当然，一个服务开发前远不止这点设计分析，我们这里就不详细描述了。从上文得知，我们需要一个
+* user rpc
+* order api
+
+两个服务来初步实现这个小demo。
+
+## 创建mall工程
+```shell
+$ cd ~/go-zero-demo
+$ mkdir mall && cd mall
+```
+
+## 创建user rpc服务
+
+* 创建user rpc服务
+ ```shell
+ $ cd ~/go-zero-demo/mall
+ $ mkdir -p user/rpc && cd user/rpc
+ ```
+
+* 添加`user.proto`文件，增加`getUser`方法
+
+ ```shell
+ $ vim ~/go-zero-demo/mall/user/rpc/user.proto
+ ```
+
+ ```protobuf
+ syntax = "proto3";
+
+ package user;
+
+ option go_package = "user";
+
+ message IdRequest {
+ string id = 1;
+ }
+
+ message UserResponse {
+ // 用户id
+ string id = 1;
+ // 用户名称
+ string name = 2;
+ // 用户性别
+ string gender = 3;
+ }
+
+ service User {
+ rpc getUser(IdRequest) returns(UserResponse);
+ }
+ ```
+* 生成代码
+
+ ```shell
+ $ cd ~/go-zero-demo/mall/user/rpc
+ $ goctl rpc proto -src user.proto -dir .
+ [goclt version <=1.2.1] protoc -I=/Users/xx/mall/user user.proto --goctl_out=plugins=grpc:/Users/xx/mall/user/user
+ [goctl version > 1.2.1] protoc -I=/Users/xx/mall/user user.proto --go_out=plugins=grpc:/Users/xx/mall/user/user
+ Done.
+ ```
+> [!TIPS]
+> 如果安装的 `protoc-gen-go` 版大于1.4.0, proto文件建议加上`go_package`
+
+* 填充业务逻辑
+
+ ```shell
+ $ vim internal/logic/getuserlogic.go
+ ```
+ ```go
+ package logic
+
+ import (
+ "context"
+
+ "go-zero-demo/mall/user/rpc/internal/svc"
+ "go-zero-demo/mall/user/rpc/user"
+
+ "github.com/tal-tech/go-zero/core/logx"
+ )
+
+ type GetUserLogic struct {
+ ctx context.Context
+ svcCtx *svc.ServiceContext
+ logx.Logger
+ }
+
+ func NewGetUserLogic(ctx context.Context, svcCtx *svc.ServiceContext) *GetUserLogic {
+ return &GetUserLogic{
+ ctx: ctx,
+ svcCtx: svcCtx,
+ Logger: logx.WithContext(ctx),
+ }
+ }
+
+ func (l *GetUserLogic) GetUser(in *user.IdRequest) (*user.UserResponse, error) {
+ return &user.UserResponse{
+ Id: "1",
+ Name: "test",
+ }, nil
+ }
+ ```
+
+* 修改配置
+
+ ```shell
+ $ vim internal/config/config.go
+ ```
+ ```go
+ package config
+
+ import (
+ "github.com/tal-tech/go-zero/zrpc"
+ )
+
+ type Config struct {
+ zrpc.RpcServerConf
+ }
+ ```
+
+## 创建order api服务
+* 创建 `order api`服务
+
+ ```shell
+ $ cd ~/go-zero-demo/mall
+ $ mkdir -p order/api && cd order/api
+ ```
+
+* 添加api文件
+ ```shell
+ $ vim order.api
+ ```
+ ```go
+ type(
+ OrderReq {
+ Id string `path:"id"`
+ }
+
+ OrderReply {
+ Id string `json:"id"`
+ Name string `json:"name"`
+ }
+ )
+ service order {
+ @handler getOrder
+ get /api/order/get/:id (OrderReq) returns (OrderReply)
+ }
+ ```
+* 生成order服务
+ ```shell
+ $ goctl api go -api order.api -dir .
+ Done.
+ ```
+* 添加user rpc配置
+
+ ```shell
+ $ vim internal/config/config.go
+ ```
+ ```go
+ package config
+
+ import "github.com/tal-tech/go-zero/rest"
+ import "github.com/tal-tech/go-zero/zrpc"
+
+ type Config struct {
+ rest.RestConf
+ UserRpc zrpc.RpcClientConf
+ }
+ ```
+* 添加yaml配置
+
+ ```shell
+ $ vim etc/order.yaml
+ ```
+ ```yaml
+ Name: order
+ Host: 0.0.0.0
+ Port: 8888
+ UserRpc:
+ Etcd:
+ Hosts:
+ - 127.0.0.1:2379
+ Key: user.rpc
+ ```
+ * 完善服务依赖
+
+ ```shell
+ $ vim internal/svc/servicecontext.go
+ ```
+ ```go
+ package svc
+
+ import (
+ "go-zero-demo/mall/order/api/internal/config"
+ "go-zero-demo/mall/user/rpc/userclient"
+
+ "github.com/tal-tech/go-zero/zrpc"
+ )
+
+ type ServiceContext struct {
+ Config config.Config
+ UserRpc userclient.User
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ UserRpc: userclient.NewUser(zrpc.MustNewClient(c.UserRpc)),
+ }
+ }
+ ```
+
+* 添加order演示逻辑
+
+ 给`getorderlogic`添加业务逻辑
+ ```shell
+ $ vim ~/go-zero-demo/mall/order/api/internal/logic/getorderlogic.go
+ ```
+ ```go
+ func (l *GetOrderLogic) GetOrder(req types.OrderReq) (*types.OrderReply, error) {
+ user, err := l.svcCtx.UserRpc.GetUser(l.ctx, &userclient.IdRequest{
+ Id: "1",
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ if user.Name != "test" {
+ return nil, errors.New("用户不存在")
+ }
+
+ return &types.OrderReply{
+ Id: req.Id,
+ Name: "test order",
+ }, nil
+ }
+ ```
+
+## 启动服务并验证
+* 启动etcd
+ ```shell
+ $ etcd
+ ```
+* 启动user rpc
+ ```shell
+ $ go run user.go -f etc/user.yaml
+ ```
+ ```text
+ Starting rpc server at 127.0.0.1:8080...
+ ```
+
+* 启动order api
+ ```shell
+ $ go run order.go -f etc/order.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+* 访问order api
+ ```shell
+ curl -i -X GET \
+ http://localhost:8888/api/order/get/1
+ ```
+
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sun, 07 Feb 2021 03:45:05 GMT
+ Content-Length: 30
+
+ {"id":"1","name":"test order"}
+ ```
+
+> [!TIP]
+> 在演示中的提及的api语法，rpc生成，goctl，goctl环境等怎么使用和安装，快速入门中不作详细概述，我们后续都会有详细的文档进行描述，你也可以点击下文的【猜你想看】快速跳转的对应文档查看。
+
+# 源码
+[mall源码](https://github.com/zeromicro/go-zero-demo/tree/master/mall)
+
+# 猜你想看
+* [goctl使用说明](goctl.md)
+* [api目录结构介绍](api-dir.md)
+* [api语法](api-grammar.md)
+* [api配置文件介绍](api-config.md)
+* [api中间件使用](middleware.md)
+* [rpc目录](rpc-dir.md)
+* [rpc配置](rpc-config.md)
+* [rpc调用方说明](rpc-call.md)
diff --git a/go-zero.dev/cn/middleware.md b/go-zero.dev/cn/middleware.md
new file mode 100644
index 00000000..87ab4cb3
--- /dev/null
+++ b/go-zero.dev/cn/middleware.md
@@ -0,0 +1,124 @@
+# 中间件使用
+在上一节，我们演示了怎么使用jwt鉴权，相信你已经掌握了对jwt的基本使用，本节我们来看一下api服务中间件怎么使用。
+
+## 中间件分类
+在go-zero中，中间件可以分为路由中间件和全局中间件，路由中间件是指某一些特定路由需要实现中间件逻辑，其和jwt类似，没有放在`jwt:xxx`下的路由不会使用中间件功能，
+而全局中间件的服务范围则是整个服务。
+
+## 中间件使用
+这里以`search`服务为例来演示中间件的使用
+
+### 路由中间件
+* 重新编写`search.api`文件，添加`middleware`声明
+ ```shell
+ $ cd service/search/cmd/api
+ $ vim search.api
+ ```
+ ```text
+ type SearchReq struct {}
+
+ type SearchReply struct {}
+
+ @server(
+ jwt: Auth
+ middleware: Example // 路由中间件声明
+ )
+ service search-api {
+ @handler search
+ get /search/do (SearchReq) returns (SearchReply)
+ }
+ ```
+* 重新生成api代码
+ ```shell
+ $ goctl api go -api search.api -dir .
+ ```
+ ```text
+ etc/search-api.yaml exists, ignored generation
+ internal/config/config.go exists, ignored generation
+ search.go exists, ignored generation
+ internal/svc/servicecontext.go exists, ignored generation
+ internal/handler/searchhandler.go exists, ignored generation
+ internal/handler/pinghandler.go exists, ignored generation
+ internal/logic/searchlogic.go exists, ignored generation
+ internal/logic/pinglogic.go exists, ignored generation
+ Done.
+ ```
+ 生成完后会在`internal`目录下多一个`middleware`的目录，这里即中间件文件，后续中间件的实现逻辑也在这里编写。
+* 完善资源依赖`ServiceContext`
+ ```shell
+ $ vim service/search/cmd/api/internal/svc/servicecontext.go
+ ```
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ Example rest.Middleware
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ Example: middleware.NewExampleMiddleware().Handle,
+ }
+ }
+ ```
+* 编写中间件逻辑
+ 这里仅添加一行日志，内容example middle，如果服务运行输出example middle则代表中间件使用起来了。
+
+ ```shell
+ $ vim service/search/cmd/api/internal/middleware/examplemiddleware.go
+ ```
+ ```go
+ package middleware
+
+ import "net/http"
+
+ type ExampleMiddleware struct {
+ }
+
+ func NewExampleMiddleware() *ExampleMiddleware {
+ return &ExampleMiddleware{}
+ }
+
+ func (m *ExampleMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ // TODO generate middleware implement function, delete after code implementation
+
+ // Passthrough to next handler if need
+ next(w, r)
+ }
+ }
+ ```
+* 启动服务验证
+ ```text
+ {"@timestamp":"2021-02-09T11:32:57.931+08","level":"info","content":"example middle"}
+ ```
+
+### 全局中间件
+通过rest.Server提供的Use方法即可
+```go
+func main() {
+ flag.Parse()
+
+ var c config.Config
+ conf.MustLoad(*configFile, &c)
+
+ ctx := svc.NewServiceContext(c)
+ server := rest.MustNewServer(c.RestConf)
+ defer server.Stop()
+
+ // 全局中间件
+ server.Use(func(next http.HandlerFunc) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ logx.Info("global middleware")
+ next(w, r)
+ }
+ })
+ handler.RegisterHandlers(server, ctx)
+
+ fmt.Printf("Starting server at %s:%d...\n", c.Host, c.Port)
+ server.Start()
+}
+```
+```text
+{"@timestamp":"2021-02-09T11:50:15.388+08","level":"info","content":"global middleware"}
+```
\ No newline at end of file
diff --git a/go-zero.dev/cn/model-gen.md b/go-zero.dev/cn/model-gen.md
new file mode 100644
index 00000000..1cd605ca
--- /dev/null
+++ b/go-zero.dev/cn/model-gen.md
@@ -0,0 +1,55 @@
+# model生成
+首先，下载好[演示工程](https://go-zero.dev/cn/resource/book.zip) 后，我们以user的model来进行代码生成演示。
+
+## 前言
+model是服务访问持久化数据层的桥梁，业务的持久化数据常存在于mysql，mongo等数据库中，我们都知道，对于一个数据库的操作莫过于CURD，
+而这些工作也会占用一部分时间来进行开发，我曾经在编写一个业务时写了40个model文件，根据不同业务需求的复杂性，平均每个model文件差不多需要
+10分钟，对于40个文件来说，400分钟的工作时间，差不多一天的工作量，而goctl工具可以在10秒钟来完成这400分钟的工作。
+
+## 准备工作
+进入演示工程book，找到user/model下的user.sql文件，将其在你自己的数据库中执行建表。
+
+## 代码生成(带缓存)
+### 方式一(ddl)
+进入`service/user/model`目录，执行命令
+```shell
+$ cd service/user/model
+$ goctl model mysql ddl -src user.sql -dir . -c
+```
+```text
+Done.
+```
+
+### 方式二(datasource)
+```shell
+$ goctl model mysql datasource -url="$datasource" -table="user" -c -dir .
+```
+```text
+Done.
+```
+> [!TIP]
+> $datasource为数据库连接地址
+
+### 方式三(intellij 插件)
+在Goland中，右键`user.sql`，依次进入并点击`New`->`Go Zero`->`Model Code`即可生成，或者打开`user.sql`文件，
+进入编辑区，使用快捷键`Command+N`（for mac OS）或者 `alt+insert`（for windows），选择`Mode Code`即可
+
+
+
+> [!TIP]
+> intellij插件生成需要安装goctl插件，详情见[intellij插件](intellij.md)
+
+## 验证生成的model文件
+查看tree
+```shell
+$ tree
+```
+```text
+.
+├── user.sql
+├── usermodel.go
+└── vars.go
+```
+
+# 猜你想看
+[model命令及其原理](goctl-model.md)
diff --git a/go-zero.dev/cn/monolithic-service.md b/go-zero.dev/cn/monolithic-service.md
new file mode 100644
index 00000000..ac31ef7d
--- /dev/null
+++ b/go-zero.dev/cn/monolithic-service.md
@@ -0,0 +1,90 @@
+# 单体服务
+
+## 前言
+由于go-zero集成了web/rpc于一体，社区有部分小伙伴会问我，go-zero的定位是否是一款微服务框架，
+答案是否定的，go-zero虽然集众多功能于一身，但你可以将其中任何一个功能独立出来去单独使用，也可以开发单体服务，
+不是说每个服务上来就一定要采用微服务的架构的设计，这点大家可以看看作者(kevin)的第四期[开源说](https://www.bilibili.com/video/BV1Jy4y127Xu) ，其中对此有详细的讲解。
+
+## 创建greet服务
+```shell
+$ cd ~/go-zero-demo
+$ goctl api new greet
+Done.
+```
+
+查看一下`greet`服务的结构
+```shell
+$ cd greet
+$ tree
+```
+```text
+.
+├── etc
+│ └── greet-api.yaml
+├── greet.api
+├── greet.go
+└── internal
+ ├── config
+ │ └── config.go
+ ├── handler
+ │ ├── greethandler.go
+ │ └── routes.go
+ ├── logic
+ │ └── greetlogic.go
+ ├── svc
+ │ └── servicecontext.go
+ └── types
+ └── types.go
+```
+由以上目录结构可以观察到，`greet`服务虽小，但"五脏俱全"。接下来我们就可以在`greetlogic.go`中编写业务代码了。
+
+## 编写逻辑
+```shell
+$ vim ~/go-zero-demo/greet/internal/logic/greetlogic.go
+```
+```go
+func (l *GreetLogic) Greet(req types.Request) (*types.Response, error) {
+ return &types.Response{
+ Message: "Hello go-zero",
+ }, nil
+}
+```
+
+## 启动并访问服务
+
+* 启动服务
+ ```shell
+ $ cd ~/go-zero-demo/greet
+ $ go run greet.go -f etc/greet-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+
+* 访问服务
+ ```shell
+ $ curl -i -X GET \
+ http://localhost:8888/from/you
+ ```
+
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sun, 07 Feb 2021 04:31:25 GMT
+ Content-Length: 27
+
+ {"message":"Hello go-zero"}
+ ```
+
+# 源码
+[greet源码](https://github.com/zeromicro/go-zero-demo/tree/master/greet)
+
+# 猜你想看
+* [goctl使用说明](goctl.md)
+* [api目录结构介绍](api-dir.md)
+* [api语法](api-grammar.md)
+* [api配置文件介绍](api-config.md)
+* [api中间件使用](middleware.md)
+
+
+
diff --git a/go-zero.dev/cn/mysql.md b/go-zero.dev/cn/mysql.md
new file mode 100644
index 00000000..5e5bb120
--- /dev/null
+++ b/go-zero.dev/cn/mysql.md
@@ -0,0 +1,180 @@
+# mysql
+
+`go-zero` 提供更易于操作的 `mysql` API。
+
+> [!TIP]
+> 但是 `stores/mysql` 定位不是一个 `orm` 框架，如果你需要通过 `sql/scheme` -> `model/struct` 逆向生成 `model` 层代码，可以使用「[goctl model](https://go-zero.dev/cn/goctl-model.html)」，这个是极好的功能。
+
+
+
+## Feature
+
+- 相比原生，提供对开发者更友好的 API
+- 完成 `queryField -> struct` 的自动赋值
+- 批量插入「bulkinserter」
+- 自带熔断
+- API 经过若干个服务的不断考验
+- 提供 `partial assignment` 特性，不强制 `struct` 的严格赋值
+
+
+
+## Connection
+下面用一个例子简单说明一下如何创建一个 `mysql` 连接的 model：
+```go
+// 1. 快速连接一个 mysql
+// datasource: mysql dsn
+heraMysql := sqlx.NewMysql(datasource)
+
+// 2. 在 servicecontext 中调用，懂model上层的logic层调用
+model.NewMysqlModel(heraMysql, tablename),
+
+// 3. model层 mysql operation
+func NewMysqlModel(conn sqlx.SqlConn, table string) *MysqlModel {
+ defer func() {
+ recover()
+ }()
+ // 4. 创建一个批量insert的 [mysql executor]
+ // conn: mysql connection; insertsql: mysql insert sql
+ bulkInserter , err := sqlx.NewBulkInserter(conn, insertsql)
+ if err != nil {
+ logx.Error("Init bulkInsert Faild")
+ panic("Init bulkInsert Faild")
+ return nil
+ }
+ return &MysqlModel{conn: conn, table: table, Bulk: bulkInserter}
+}
+```
+
+
+## CRUD
+
+准备一个 `User model`
+```go
+var userBuilderQueryRows = strings.Join(builderx.FieldNames(&User{}), ",")
+
+type User struct {
+ Avatar string `db:"avatar"` // 头像
+ UserName string `db:"user_name"` // 姓名
+ Sex int `db:"sex"` // 1男,2女
+ MobilePhone string `db:"mobile_phone"` // 手机号
+}
+```
+其中 `userBuilderQueryRows` ： `go-zero` 中提供 `struct -> [field...]` 的转化，开发者可以将此当成模版直接使用。
+### insert
+```go
+// 一个实际的insert model层操作
+func (um *UserModel) Insert(user *User) (int64, error) {
+ const insertsql = `insert into `+um.table+` (`+userBuilderQueryRows+`) values(?, ?, ?)`
+ // insert op
+ res, err := um.conn.Exec(insertsql, user.Avatar, user.UserName, user.Sex, user.MobilePhone)
+ if err != nil {
+ logx.Errorf("insert User Position Model Model err, err=%v", err)
+ return -1, err
+ }
+ id, err := res.LastInsertId()
+ if err != nil {
+ logx.Errorf("insert User Model to Id parse id err,err=%v", err)
+ return -1, err
+ }
+ return id, nil
+}
+```
+
+- 拼接 `insertsql`
+- 将 `insertsql` 以及占位符对应的 `struct field` 传入 -> `con.Exex(insertsql, field...)`
+
+
+> [!WARNING]
+> `conn.Exec(sql, args...)` ： `args...` 需对应 `sql` 中的占位符。不然会出现赋值异常的问题。
+
+
+`go-zero` 将涉及 `mysql` 修改的操作统一抽象为 `Exec()` 。所以 `insert/update/delete` 操作本质上是一致的。其余两个操作，开发者按照上述 `insert` 流程尝试即可。
+
+
+### query
+
+
+只需要传入 `querysql` 和 `model` 结构体，就可以获取到被赋值好的 `model` 。无需开发者手动赋值。
+```go
+func (um *UserModel) FindOne(uid int64) (*User, error) {
+ var user User
+ const querysql = `select `+userBuilderQueryRows+` from `+um.table+` where id=? limit 1`
+ err := um.conn.QueryRow(&user, querysql, uid)
+ if err != nil {
+ logx.Errorf("userId.findOne error, id=%d, err=%s", uid, err.Error())
+ if err == sqlx.ErrNotFound {
+ return nil, ErrNotFound
+ }
+ return nil, err
+ }
+ return &user, nil
+}
+```
+
+- 声明 `model struct` ，拼接 `querysql`
+- `conn.QueryRow(&model, querysql, args...)` ： `args...` 与 `querysql` 中的占位符对应。
+
+
+
+> [!WARNING]
+> `QueryRow()` 中第一个参数需要传入 `Ptr` 「底层需要反射对 `struct` 进行赋值」
+
+上述是查询一条记录，如果需要查询多条记录时，可以使用 `conn.QueryRows()`
+```go
+func (um *UserModel) FindOne(sex int) ([]*User, error) {
+ users := make([]*User, 0)
+ const querysql = `select `+userBuilderQueryRows+` from `+um.table+` where sex=?`
+ err := um.conn.QueryRows(&users, querysql, sex)
+ if err != nil {
+ logx.Errorf("usersSex.findOne error, sex=%d, err=%s", uid, err.Error())
+ if err == sqlx.ErrNotFound {
+ return nil, ErrNotFound
+ }
+ return nil, err
+ }
+ return users, nil
+}
+```
+与 `QueryRow()` 不同的地方在于： `model` 需要设置成 `Slice` ，因为是查询多行，需要对多个 `model` 赋值。但同时需要注意️：第一个参数需要传入 `Ptr`
+
+### querypartial
+
+
+从使用上，与上述的 `QueryRow()` 无异「这正体现了 `go-zero` 高度的抽象设计」。
+
+
+区别：
+
+- `QueryRow()` ： `len(querysql fields) == len(struct)` ，且一一对应
+- `QueryRowPartial()` ：`len(querysql fields) <= len(struct)`
+
+
+
+numA：数据库字段数；numB：定义的 `struct` 属性数。
+如果 `numA < numB` ，但是你恰恰又需要统一多处的查询时「定义了多个 `struct` 返回不同的用途，恰恰都可以使用相同的 `querysql` 」，就可以使用 `QueryRowPartial()`
+
+
+## 事务
+
+
+要在事务中执行一系列操作，一般流程如下：
+```go
+var insertsql = `insert into User(uid, username, mobilephone) values (?, ?, ?)`
+err := usermodel.conn.Transact(func(session sqlx.Session) error {
+ stmt, err := session.Prepare(insertsql)
+ if err != nil {
+ return err
+ }
+ defer stmt.Close()
+
+ // 返回任何错误都会回滚事务
+ if _, err := stmt.Exec(uid, username, mobilephone); err != nil {
+ logx.Errorf("insert userinfo stmt exec: %s", err)
+ return err
+ }
+
+ // 还可以继续执行 insert/update/delete 相关操作
+ return nil
+})
+```
+如同上述例子，开发者只需将 **事务** 中的操作都包装在一个函数 `func(session sqlx.Session) error {}` 中即可，如果事务中的操作返回任何错误， `Transact()` 都会自动回滚事务。
diff --git a/go-zero.dev/cn/naming-spec.md b/go-zero.dev/cn/naming-spec.md
new file mode 100644
index 00000000..69773f6c
--- /dev/null
+++ b/go-zero.dev/cn/naming-spec.md
@@ -0,0 +1,49 @@
+# 命名规范
+在任何语言开发中，都有其语言领域的一些命名规范，好的命名可以：
+* 降低代码阅读成本
+* 降低维护难度
+* 降低代码复杂度
+
+## 规范建议
+在我们实际开发中，有很多开发人可能是由某一语言转到另外一个语言领域，在转到另外一门语言后，
+我们都会保留着对旧语言的编程习惯，在这里，我建议的是，虽然不同语言之前的某些规范可能是相通的，
+但是我们最好能够按照官方的一些demo来熟悉是渐渐适应当前语言的编程规范，而不是直接将原来语言的编程规范也随之迁移过来。
+
+## 命名准则
+* 当变量名称在定义和最后一次使用之间的距离很短时，简短的名称看起来会更好。
+* 变量命名应尽量描述其内容，而不是类型
+* 常量命名应尽量描述其值，而不是如何使用这个值
+* 在遇到for，if等循环或分支时，推荐单个字母命名来标识参数和返回值
+* method、interface、type、package推荐使用单词命名
+* package名称也是命名的一部分，请尽量将其利用起来
+* 使用一致的命名风格
+
+## 文件命名规范
+* 全部小写
+* 除unit test外避免下划线(_)
+* 文件名称不宜过长
+
+## 变量命名规范参考
+* 首字母小写
+* 驼峰命名
+* 见名知义，避免拼音替代英文
+* 不建议包含下划线(_)
+* 不建议包含数字
+
+**适用范围**
+* 局部变量
+* 函数出参、入参
+
+## 函数、常量命名规范
+* 驼峰式命名
+* 可exported的必须首字母大写
+* 不可exported的必须首字母小写
+* 避免全部大写与下划线(_)组合
+
+
+> [!TIP]
+> 如果是go-zero代码贡献，则必须严格遵循此命名规范
+
+
+# 参考文档
+* [Practical Go: Real world advice for writing maintainable Go programs](https://dave.cheney.net/practical-go/presentations/gophercon-singapore-2019.html#_simplicity)
diff --git a/go-zero.dev/cn/online-exchange.md b/go-zero.dev/cn/online-exchange.md
new file mode 100644
index 00000000..a7f90bc9
--- /dev/null
+++ b/go-zero.dev/cn/online-exchange.md
@@ -0,0 +1,154 @@
+# 10月3日线上交流问题汇总
+
+- go-zero适用场景
+ - 希望说说应用场景，各个场景下的优势
+ - 高并发的微服务系统
+ - 支撑千万级日活，百万级QPS
+ - 完整的微服务治理能力
+ - 支持自定义中间件
+ - 很好的管理了数据库和缓存
+ - 有效隔离故障
+ - 低并发的单体系统
+ - 这种系统直接使用api层即可，无需rpc服务
+ - 各个功能的使用场景以及使用案例
+ - 限流
+ - 熔断
+ - 降载
+ - 超时
+ - 可观测性
+- go-zero的实际体验
+ - 服务很稳
+ - 前后端接口一致性，一个api文件即可生成前后端代码
+ - 规范、代码量少，意味着bug少
+ - 免除api文档，极大降低沟通成本
+ - 代码结构完全一致，便于维护和接手
+- 微服务的项目结构， monorepo的 CICD 处理
+
+```
+ bookstore
+ ├── api
+ │ ├── etc
+ │ └── internal
+ │ ├── config
+ │ ├── handler
+ │ ├── logic
+ │ ├── svc
+ │ └── types
+ └── rpc
+ ├── add
+ │ ├── adder
+ │ ├── etc
+ │ ├── internal
+ │ │ ├── config
+ │ │ ├── logic
+ │ │ ├── server
+ │ │ └── svc
+ │ └── pb
+ ├── check
+ │ ├── checker
+ │ ├── etc
+ │ ├── internal
+ │ │ ├── config
+ │ │ ├── logic
+ │ │ ├── server
+ │ │ └── svc
+ │ └── pb
+ └── model
+```
+
+mono repo的CI我们是通过gitlab做的，CD使用jenkins
+CI尽可能更严格的模式，比如-race，使用sonar等工具
+CD有开发、测试、预发、灰度和正式集群
+晚6点上灰度、无故障的话第二天10点自动同步到正式集群
+正式集群分为多个k8s集群，有效的防止单集群故障，直接摘除即可，集群升级更有好
+- 如何部署，如何监控？
+ - 全量K8S，通过jenkins自动打包成docker镜像，按照时间打包tag，这样可以一眼看出哪一天的镜像
+ - 上面已经讲了，预发->灰度->正式
+ - Prometheus+自建dashboard服务
+ - 基于日志检测服务和请求异常
+- 如果打算换go-zero框架重构业务，如何做好线上业务稳定安全用户无感切换？另外咨询下如何进行服务划分？
+ - 逐步替换，从外到内，加个proxy来校对，校对一周后可以切换
+ - 如有数据库重构，则需要做好新老同步
+ - 服务划分按照业务来，遵循从粗到细的原则，避免一个api一个微服务
+ - 数据拆分对于微服务来讲尤为重要，上层好拆，数据难拆，尽可能保证按照业务拆分数据
+- 服务发现
+ - 服务发现 etcd 的 key 的设计
+ - 服务key+时间戳，服务进程数存在时间戳冲突的概率极低，忽略
+ - etcd服务发现与治理， 异常捕获与处理异常
+ - 为啥k8s还使用etcd做服务发现，因为dns的刷新有延迟，导致滚动更新会有大量失败，而etcd可以做到完全无损更新
+ - etcd集群直接部署在k8s集群内，因为多个正式集群，集群单点和注册避免混乱
+ - 针对etcd异常或者leader切换，自动侦测并刷新，当etcd有异常不能恢复时，不会刷新服务列表，保障服务依然可用
+- 缓存的设计与使用案例
+ - 分布式多redis集群，线上最大几十个集群为同一个服务提供缓存服务
+ - 无缝扩缩容
+ - 不存在没有过期时间的缓存，避免大量不常使用的数据占用资源，默认一周
+ - 缓存穿透，没有的数据会短暂缓存一分钟，避免刷接口或大量不存在的数据请求带垮系统
+ - 缓存击穿，一个进程只会刷新一次同一个数据，避免热点数据被大量同时加载
+ - 缓存雪崩，对缓存过期时间自动做了jitter，5%的标准变差，使得一周的过期时间分布在16小时内，有效防止了雪崩
+ - 我们线上数据库都有缓存，否则无法支撑海量并发
+ - 自动缓存管理已经内置于go-zero，并可以通过goctl自动生成代码
+- 能否讲解下， 中间件，拦截器的设计思想
+
+ - 洋葱模型
+ - 本中间件处理，比如限流，熔断等，然后决定是否调用next
+ - next调用
+ - 对next调用返回结果做处理
+- 微服务的事务处理怎么实现好，gozero分布式事务设计和实现，有什么好中间件推荐
+ - 2PC，两阶段提交
+ - TCC，Try-Confirm-Cancel
+ - 消息队列，最大尝试
+ - 人工补偿
+- 多级 goroutine 的异常捕获 ，怎么设计比较好
+ - 微服务系统请求异常应该隔离，不能让单个异常请求带崩整个进程
+ - go-zero自带了RunSafe/GoSafe，用来防止单个异常请求导致进程崩溃
+ - 监控需要跟上，防止异常过量而不自知
+ - fail fast和故障隔离的矛盾点
+- k8s配置的生成与使用(gateway, service, slb)
+ - 内部自动生成k8s的yaml文件，过于依赖配置而未开源
+ - 打算在bookstore的示例里加上k8s配置样板
+ - slb->nginx->nodeport->api gateway->rpc service
+- gateway限流、熔断和降载
+ - 限流分为两种：并发控制和分布式限流
+ - 并发控制用来防止瞬间过量请求，保护系统不被打垮
+ - 分布式限流用来给不同服务配置不同的quota
+ - 熔断是为了对依赖的服务进行保护，当一个服务出现大量异常的时候，调用者应该给予保护，使其有机会恢复正常，同时也达到fail fast的效果
+ - 降载是为了保护当前进程资源耗尽而陷入彻底不可用，确保尽可能服务好能承载的最大请求量
+ - 降载配合k8s，可以有效保护k8s扩容，k8s扩容分钟级，go-zero降载秒级
+- 介绍core中好用的组件，如timingwheel等，讲讲设计思路
+ - 布隆过滤器
+ - 进程内cache
+ - RollingWindow
+ - TimingWheel
+ - 各种executors
+ - fx包，map/reduce/filter/sort/group/distinct/head/tail...
+ - 一致性hash实现
+ - 分布式限流实现
+ - mapreduce，带cancel能力
+ - syncx包里有大量的并发工具
+- 如何快速增加一种rpc协议支持，將跨机发现改为调本机节点，并关闭复杂filter和负载均衡功能
+ - go-zero跟grpc关系还是比较紧密的，设计之初没有考虑支持grpc以外的协议
+ - 如果要增加的话，那就只能fork出来魔改了
+ - 调本机直接用direct的scheme即可
+ - 为啥要去掉filter和负载均衡？如果要去的话，fork了改，但没必要
+- 日志和监控和链路追踪的设计和实现思路，最好有大概图解
+ - 日志和监控我们使用prometheus, 自定义dashboard服务，捆绑提交数据（每分钟）
+ - 链路追踪可以看出调用关系，自动记录trace日志
+
+- go-zero框架有用到什么池化技术吗？如果有，在哪些core代码里面可以参考
+ - 一般不需要提前优化，过度优化是大忌
+ - core/syncx/pool.go里面定义了带过期时间的通用池化技术
+- go-zero用到了那些性能测试方法框架，有代码参考吗？可以说说思路和经验
+ - go benchmark
+ - 压测可以通过现有业务日志样本，来按照预估等比放大
+ - 压测一定要压到系统扛不住，看第一个瓶颈在哪里，改完再压，循环
+- 说一下代码的抽象经验和心得
+ - Don’t repeat yourself
+ - 你未必需要它，之前经常有业务开发人员问我可不可以增加这个功能或那个功能，我一般都会仔细询问深层次目的，很多时候会发现其实这个功能是多余的，不需要才是最佳实践
+ - Martin Fowler提出出现三次再抽象的原则，有时有些同事会找我往框架里增加一个功能，我思考后经常会回答这个你先在业务层写，其它地方也有需要了你再告诉我，三次出现我会考虑集成到框架里
+ - 一个文件应该尽量只做一件事，每个文件尽可能控制在200行以内，一个函数尽可能控制在50行以内，这样不需要滚动就可以看到整个函数
+ - 需要抽象和提炼的能力，多去思考，经常回头思考之前的架构或实现
+- 你会就go-zero 框架从设计到实践出书吗？框架以后的发展规划是什么？
+ - 暂无出书计划，做好框架是最重要的
+ - 继续着眼于工程效率
+ - 提升服务治理能力
+ - 帮助业务开发尽可能快速落地
diff --git a/go-zero.dev/cn/periodlimit.md b/go-zero.dev/cn/periodlimit.md
new file mode 100644
index 00000000..74100aa2
--- /dev/null
+++ b/go-zero.dev/cn/periodlimit.md
@@ -0,0 +1,127 @@
+# periodlimit
+
+不管是在单体服务中还是在微服务中，开发者为前端提供的API接口都是有访问上限的，当访问频率或者并发量超过其承受范围时候，我们就必须考虑限流来保证接口的可用性或者降级可用性。即接口也需要安装上保险丝，以防止非预期的请求对系统压力过大而引起的系统瘫痪。
+
+
+本文就来介绍一下 `periodlimit` 。
+## 使用
+```go
+const (
+ seconds = 1
+ total = 100
+ quota = 5
+)
+// New limiter
+l := NewPeriodLimit(seconds, quota, redis.NewRedis(s.Addr(), redis.NodeType), "periodlimit")
+
+// take source
+code, err := l.Take("first")
+if err != nil {
+ logx.Error(err)
+ return true
+}
+
+// switch val => process request
+switch code {
+ case limit.OverQuota:
+ logx.Errorf("OverQuota key: %v", key)
+ return false
+ case limit.Allowed:
+ logx.Infof("AllowedQuota key: %v", key)
+ return true
+ case limit.HitQuota:
+ logx.Errorf("HitQuota key: %v", key)
+ // todo: maybe we need to let users know they hit the quota
+ return false
+ default:
+ logx.Errorf("DefaultQuota key: %v", key)
+ // unknown response, we just let the sms go
+ return true
+}
+```
+## periodlimit
+
+
+`go-zero` 采取 **滑动窗口** 计数的方式，计算一段时间内对同一个资源的访问次数，如果超过指定的 `limit` ，则拒绝访问。当然如果你是在一段时间内访问不同的资源，每一个资源访问量都不超过 `limit` ，此种情况是允许大量请求进来的。
+
+
+而在一个分布式系统中，存在多个微服务提供服务。所以当瞬间的流量同时访问同一个资源，如何让计数器在分布式系统中正常计数？ 同时在计算资源访问时，可能会涉及多个计算，如何保证计算的原子性？
+
+
+- `go-zero` 借助 `redis` 的 `incrby` 做资源访问计数
+- 采用 `lua script` 做整个窗口计算，保证计算的原子性
+
+
+
+下面来看看 `lua script` 控制的几个关键属性：
+
+| **argument** | **mean** |
+| --- | --- |
+| key[1] | 访问资源的标示 |
+| ARGV[1] | limit => 请求总数，超过则限速。可设置为 QPS |
+| ARGV[2] | window大小 => 滑动窗口，用 ttl 模拟出滑动的效果 |
+
+```lua
+-- to be compatible with aliyun redis,
+-- we cannot use `local key = KEYS[1]` to reuse thekey
+local limit = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+-- incrbt key 1 => key visis++
+local current = redis.call("INCRBY", KEYS[1], 1)
+-- 如果是第一次访问，设置过期时间 => TTL = window size
+-- 因为是只限制一段时间的访问次数
+if current == 1 then
+ redis.call("expire", KEYS[1], window)
+ return 1
+elseif current < limit then
+ return 1
+elseif current == limit then
+ return 2
+else
+ return 0
+end
+```
+至于上述的 `return code` ，返回给调用方。由调用方来决定请求后续的操作：
+
+| **return code** | **tag** | call code | **mean** |
+| --- | --- | --- | --- |
+| 0 | OverQuota | 3 | **over limit** |
+| 1 | Allowed | 1 | **in limit** |
+| 2 | HitQuota | 2 | **hit limit** |
+
+下面这张图描述了请求进入的过程，以及请求触发 `limit` 时后续发生的情况：
+
+
+## 后续处理
+
+
+如果在服务某个时间点，请求大批量打进来，`periodlimit` 短期时间内达到 `limit` 阈值，而且设置的时间范围还远远没有到达。后续请求的处理就成为问题。
+
+
+`periodlimit` 中并没有处理，而是返回 `code` 。把后续请求的处理交给了开发者自己处理。
+
+
+1. 如果不做处理，那就是简单的将请求拒绝
+1. 如果需要处理这些请求，开发者可以借助 `mq` 将请求缓冲，减缓请求的压力
+1. 采用 `tokenlimit`，允许暂时的流量冲击
+
+
+
+所以下一篇我们就来聊聊 `tokenlimit`
+
+
+## 总结
+`go-zero` 中的 `periodlimit` 限流方案是基于 `redis` 计数器，通过调用 `redis lua script` ，保证计数过程的原子性，同时保证在分布式的情况下计数是正常的。但是这种方案存在缺点，因为它要记录时间窗口内的所有行为记录，如果这个量特别大的时候，内存消耗会变得非常严重。
+
+
+## 参考
+
+
+- [go-zero periodlimit](https://github.com/zeromicro/go-zero/blob/master/core/limit/periodlimit.go)
+- [分布式服务限流实战，已经为你排好坑了](https://www.infoq.cn/article/Qg2tX8fyw5Vt-f3HH673)
+- [tokenlimit](tokenlimit.md)
+
+
+
+
+
diff --git a/go-zero.dev/cn/plugin-center.md b/go-zero.dev/cn/plugin-center.md
new file mode 100644
index 00000000..13b5ff9a
--- /dev/null
+++ b/go-zero.dev/cn/plugin-center.md
@@ -0,0 +1,16 @@
+# 插件中心
+goctl api提供了对plugin命令来支持对api进行功能扩展，当goctl api中的功能不满足你的使用，
+或者需要对goctl api进行功能自定义的扩展，那么插件功能将非常适合开发人员进行自给自足，详情见
+[goctl plugin](goctl-plugin.md)
+
+## 插件资源
+* [goctl-go-compact](https://github.com/zeromicro/goctl-go-compact)
+ goctl默认的一个路由一个文件合并成一个文件
+* [goctl-swagger](https://github.com/zeromicro/goctl-swagger)
+ 通过api文件生成swagger文档
+* [goctl-php](https://github.com/zeromicro/goctl-php)
+ goctl-php是一款基于goctl的插件，用于生成 php 调用端（服务端） http server请求代码
+
+# 猜你想看
+* [goctl插件](goctl-plugin.md)
+* [api语法介绍](api-grammar.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/prepare-other.md b/go-zero.dev/cn/prepare-other.md
new file mode 100644
index 00000000..acebdc4e
--- /dev/null
+++ b/go-zero.dev/cn/prepare-other.md
@@ -0,0 +1,9 @@
+# 其他
+在之前我们已经对Go环境、Go Module配置、Goctl、protoc&protoc-gen-go安装准备就绪，这些是开发人员在开发阶段必须要准备的环境，而接下来的环境你可以选择性的安装，
+因为这些环境一般存在于服务器（安装工作运维会替你完成），但是为了后续**演示**流程能够完整走下去，我建议大家在本地也安装一下，因为我们的演示环境大部分会以本地为主。
+以下仅给出了需要的准备工作，不以文档篇幅作详细介绍了。
+
+## 其他环境
+* [etcd](https://etcd.io/docs/current/rfc/v3api/)
+* [redis](https://redis.io/)
+* [mysql](https://www.mysql.com/)
\ No newline at end of file
diff --git a/go-zero.dev/cn/prepare.md b/go-zero.dev/cn/prepare.md
new file mode 100644
index 00000000..146d23dd
--- /dev/null
+++ b/go-zero.dev/cn/prepare.md
@@ -0,0 +1,8 @@
+# 准备工作
+在正式进入实际开发之前，我们需要做一些准备工作，比如：Go环境的安装，grpc代码生成使用的工具安装，
+必备工具Goctl的安装，Golang环境配置等，本节将包含以下小节：
+* [golang安装](golang-install.md)
+* [go modudle配置](gomod-config.md)
+* [goctl安装](goctl-install.md)
+* [protoc&protoc-gen-go安装](protoc-install.md)
+* [其他](prepare-other.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/project-dev.md b/go-zero.dev/cn/project-dev.md
new file mode 100644
index 00000000..67276dd1
--- /dev/null
+++ b/go-zero.dev/cn/project-dev.md
@@ -0,0 +1,32 @@
+# 项目开发
+在前面的章节我们已经从一些概念、背景、快速入门等维度介绍了一下go-zero，看到这里，相信你对go-zero已经有了一些了解，
+从这里开始，我们将会从环境准备到服务部署整个流程开始进行讲解，为了保证大家能够彻底弄懂go-zero的开发流程，那就准备你的耐心来接着往下走吧。
+在章节中，将包含以下小节：
+* [准备工作](prepare.md)
+* [golang安装](golang-install.md)
+* [go modudle配置](gomod-config.md)
+* [goctl安装](goctl-install.md)
+* [protoc&protoc-gen-go安装](protoc-install.md)
+* [其他](prepare-other.md)
+* [开发规范](dev-specification.md)
+ * [命名规范](naming-spec.md)
+ * [路由规范](route-naming-spec.md)
+ * [编码规范](coding-spec.md)
+* [开发流程](dev-flow.md)
+* [配置介绍](config-introduction.md)
+ * [api配置](api-config.md)
+ * [rpc配置](rpc-config.md)
+* [业务开发](business-dev.md)
+ * [目录拆分](service-design.md)
+ * [model生成](model-gen.md)
+ * [api文件编写](api-coding.md)
+ * [业务编码](business-coding.md)
+ * [jwt鉴权](jwt.md)
+ * [中间件使用](middleware.md)
+ * [rpc服务编写与调用](rpc-call.md)
+ * [错误处理](error-handle.md)
+* [CI/CD](ci-cd.md)
+* [服务部署](service-deployment.md)
+* [日志收集](log-collection.md)
+* [链路追踪](trace.md)
+* [服务监控](service-monitor.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/protoc-install.md b/go-zero.dev/cn/protoc-install.md
new file mode 100644
index 00000000..5afd051b
--- /dev/null
+++ b/go-zero.dev/cn/protoc-install.md
@@ -0,0 +1,56 @@
+# protoc & protoc-gen-go安装
+
+## 前言
+protoc是一款用C++编写的工具，其可以将proto文件翻译为指定语言的代码。在go-zero的微服务中，我们采用grpc进行服务间的通信，而grpc的编写就需要用到protoc和翻译成go语言rpc stub代码的插件protoc-gen-go。
+
+本文演示环境
+* mac OS
+* protoc 3.14.0
+
+## protoc安装
+
+* 进入[protobuf release](https://github.com/protocolbuffers/protobuf/releases) 页面，选择适合自己操作系统的压缩包文件
+* 解压`protoc-3.14.0-osx-x86_64.zip`并进入`protoc-3.14.0-osx-x86_64`
+ ```shell
+ $ cd protoc-3.14.0-osx-x86_64/bin
+ ```
+* 将启动的`protoc`二进制文件移动到被添加到环境变量的任意path下，如`$GOPATH/bin`，这里不建议直接将其和系统的以下path放在一起。
+ ```shell
+ $ mv protoc $GOPATH/bin
+ ```
+ > [!TIP]
+ > $GOPATH为你本机的实际文件夹地址
+* 验证安装结果
+ ```shell
+ $ protoc --version
+ ```
+ ```shell
+ libprotoc 3.14.0
+ ```
+
+## protoc-gen-*安装
+在goctl版本大于1.2.1时，则不需要安装 `protoc-gen-go` 插件了，因为在该版本以后，goctl已经实现了作为 `protoc` 的插件了，goctl在指定 `goctl xxx` 命令时会自动
+将 `goctl` 创建一个符号链接 `protoc-gen-goctl` ，在生成pb.go时会按照如下逻辑生成：
+1. 检测环境变量中是否存在 `protoc-gen-goctl` 插件，如果是，则跳转到第3步
+2. 检测环境变量中是否存在 `protoc-gen-go` 插件，如果不存在，则生成流程结束
+3. 根据检测到的插件生成pb.go
+
+> [!TIPS]
+>
+> Windows 在创建符号链接可能会报错， `A required privilege is not held by the client.`, 原因是在Windows下执行goctl需要"以管理员身份"运行。
+>
+
+* 下载安装`protoc-gen-go`
+
+ 如果goctl 版本已经是1.2.1以后了，可以忽略此步骤。
+ ```shell
+ $ go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2
+ ```
+ ```text
+ go: found github.com/golang/protobuf/protoc-gen-go in github.com/golang/protobuf v1.4.3
+ go: google.golang.org/protobuf upgrade => v1.25.0
+ ```
+* 将protoc-gen-go移动到被添加环境变量的任意path下，如`$GOPATH/bin`，由于`go get`后的二进制本身就在`$GOPATH/bin`目录中，因此只要确保你的`$GOPATH/bin`在环境变量即可。
+
+> **[!WARNING]
+> protoc-gen-go安装失败请阅读[常见错误处理](error.md)
diff --git a/go-zero.dev/cn/quick-start.md b/go-zero.dev/cn/quick-start.md
new file mode 100644
index 00000000..b7baa4fb
--- /dev/null
+++ b/go-zero.dev/cn/quick-start.md
@@ -0,0 +1,6 @@
+# 快速开发
+
+本节主要通过对 api/rpc 等服务快速开始来让大家对使用 go-zero 开发的工程有一个宏观概念，更加详细的介绍我们将在后续一一展开。如果您已经参考 [准备工作](prepare.md) 做好环境及工具的准备，请跟随以下小节开始体验：
+
+* [单体服务](monolithic-service.md)
+* [微服务](micro-service.md)
diff --git a/go-zero.dev/cn/redis-cache.md b/go-zero.dev/cn/redis-cache.md
new file mode 100644
index 00000000..19961508
--- /dev/null
+++ b/go-zero.dev/cn/redis-cache.md
@@ -0,0 +1,269 @@
+# go-zero缓存设计之持久层缓存
+
+## 缓存设计原理
+
+我们对缓存是只删除，不做更新，一旦DB里数据出现修改，我们就会直接删除对应的缓存，而不是去更新。
+
+我们看看删除缓存的顺序怎样才是正确的。
+
+* 先删除缓存，再更新DB
+
+
+
+我们看两个并发请求的情况，A请求需要更新数据，先删除了缓存，然后B请求来读取数据，此时缓存没有数据，就会从DB加载数据并写回缓存，然后A更新了DB，那么此时缓存内的数据就会一直是脏数据，直到缓存过期或者有新的更新数据的请求。如图
+
+
+
+* 先更新DB，再删除缓存
+
+ 
+
+A请求先更新DB，然后B请求来读取数据，此时返回的是老数据，此时可以认为是A请求还没更新完，最终一致性，可以接受，然后A删除了缓存，后续请求都会拿到最新数据，如图
+
+
+让我们再来看一下正常的请求流程：
+
+* 第一个请求更新DB，并删除了缓存
+* 第二个请求读取缓存，没有数据，就从DB读取数据，并回写到缓存里
+* 后续读请求都可以直接从缓存读取
+ 
+
+我们再看一下DB查询有哪些情况，假设行记录里有ABCDEFG七列数据：
+
+* 只查询部分列数据的请求，比如请求其中的ABC，CDE或者EFG等，如图
+ 
+
+* 查询单条完整行记录，如图
+ 
+
+* 查询多条行记录的部分或全部列，如图
+ 
+
+对于上面三种情况，首先，我们不用部分查询，因为部分查询没法缓存，一旦缓存了，数据有更新，没法定位到有哪些数据需要删除；其次，对于多行的查询，根据实际场景和需要，我们会在业务层建立对应的从查询条件到主键的映射；而对于单行完整记录的查询，go-zero 内置了完整的缓存管理方式。所以核心原则是：**go-zero 缓存的一定是完整的行记录**。
+
+下面我们来详细介绍 go-zero 内置的三种场景的缓存处理方式：
+
+* 基于主键的缓存
+ ```text
+ PRIMARY KEY (`id`)
+ ```
+
+这种相对来讲是最容易处理的缓存，只需要在 redis 里用 primary key 作为 key 来缓存行记录即可。
+
+* 基于唯一索引的缓存
+ 
+
+在做基于索引的缓存设计的时候我借鉴了 database 索引的设计方法，在 database 设计里，如果通过索引去查数据时，引擎会先在 索引->主键 的 tree 里面查找到主键，然后再通过主键去查询行记录，就是引入了一个间接层去解决索引到行记录的对应问题。在 go-zero 的缓存设计里也是同样的原理。
+
+基于索引的缓存又分为单列唯一索引和多列唯一索引：
+
+但是对于 go-zero 来说，单列和多列只是生成缓存 key 的方式不同而已，背后的控制逻辑是一样的。然后 go-zero 内置的缓存管理就比较好的控制了数据一致性问题，同时也内置防止了缓存的击穿、穿透、雪崩问题（这些在 gopherchina 大会上分享的时候仔细讲过，见后续 gopherchina 分享视频）。
+
+另外，go-zero 内置了缓存访问量、访问命中率统计，如下所示：
+
+```text
+dbcache(sqlc) - qpm: 5057, hit_ratio: 99.7%, hit: 5044, miss: 13, db_fails: 0
+```
+
+可以看到比较详细的统计信息，便于我们来分析缓存的使用情况，对于缓存命中率极低或者请求量极小的情况，我们就可以去掉缓存了，这样也可以降低成本。
+
+* 单列唯一索引如下：
+ ```text
+ UNIQUE KEY `product_idx` (`product`)
+ ```
+
+* 多列唯一索引如下：
+ ```text
+ UNIQUE KEY `vendor_product_idx` (`vendor`, `product`)
+ ```
+## 缓存代码解读
+
+### 1.基于主键的缓存逻辑
+
+
+具体实现代码如下：
+```go
+func (cc CachedConn) QueryRow(v interface{}, key string, query QueryFn) error {
+ return cc.cache.Take(v, key, func(v interface{}) error {
+ return query(cc.db, v)
+ })
+}
+```
+
+这里的 `Take` 方法是先从缓存里去通过 `key` 拿数据，如果拿到就直接返回，如果拿不到，那么就通过 `query` 方法去 `DB` 读取完整行记录并写回缓存，然后再返回数据。整个逻辑还是比较简单易懂的。
+
+我们详细看看 `Take` 的实现：
+```go
+func (c cacheNode) Take(v interface{}, key string, query func(v interface{}) error) error {
+ return c.doTake(v, key, query, func(v interface{}) error {
+ return c.SetCache(key, v)
+ })
+}
+```
+
+`Take` 的逻辑如下：
+
+* 用 key 从缓存里查找数据
+* 如果找到，则返回数据
+* 如果找不到，用 query 方法去读取数据
+* 读到后调用 c.SetCache(key, v) 设置缓存
+
+其中的 `doTake` 代码和解释如下：
+```go
+// v - 需要读取的数据对象
+// key - 缓存key
+// query - 用来从DB读取完整数据的方法
+// cacheVal - 用来写缓存的方法
+func (c cacheNode) doTake(v interface{}, key string, query func(v interface{}) error,
+ cacheVal func(v interface{}) error) error {
+ // 用barrier来防止缓存击穿，确保一个进程内只有一个请求去加载key对应的数据
+ val, fresh, err := c.barrier.DoEx(key, func() (interface{}, error) {
+ // 从cache里读取数据
+ if err := c.doGetCache(key, v); err != nil {
+ // 如果是预先放进来的placeholder（用来防止缓存穿透）的，那么就返回预设的errNotFound
+ // 如果是未知错误，那么就直接返回，因为我们不能放弃缓存出错而直接把所有请求去请求DB，
+ // 这样在高并发的场景下会把DB打挂掉的
+ if err == errPlaceholder {
+ return nil, c.errNotFound
+ } else if err != c.errNotFound {
+ // why we just return the error instead of query from db,
+ // because we don't allow the disaster pass to the DBs.
+ // fail fast, in case we bring down the dbs.
+ return nil, err
+ }
+
+ // 请求DB
+ // 如果返回的error是errNotFound，那么我们就需要在缓存里设置placeholder，防止缓存穿透
+ if err = query(v); err == c.errNotFound {
+ if err = c.setCacheWithNotFound(key); err != nil {
+ logx.Error(err)
+ }
+
+ return nil, c.errNotFound
+ } else if err != nil {
+ // 统计DB失败
+ c.stat.IncrementDbFails()
+ return nil, err
+ }
+
+ // 把数据写入缓存
+ if err = cacheVal(v); err != nil {
+ logx.Error(err)
+ }
+ }
+
+ // 返回json序列化的数据
+ return jsonx.Marshal(v)
+ })
+ if err != nil {
+ return err
+ }
+ if fresh {
+ return nil
+ }
+
+ // got the result from previous ongoing query
+ c.stat.IncrementTotal()
+ c.stat.IncrementHit()
+
+ // 把数据写入到传入的v对象里
+ return jsonx.Unmarshal(val.([]byte), v)
+}
+```
+
+### 2. 基于唯一索引的缓存逻辑
+因为这块比较复杂，所以我用不同颜色标识出来了响应的代码块和逻辑，`block 2` 其实跟基于主键的缓存是一样的，这里主要讲 `block 1` 的逻辑。
+
+
+代码块的 block 1 部分分为两种情况：
+
+* 通过索引能够从缓存里找到主键，此时就直接用主键走 `block 2` 的逻辑了，后续同上面基于主键的缓存逻辑
+
+* 通过索引无法从缓存里找到主键
+ * 通过索引从DB里查询完整行记录，如有 `error`，返回
+ * 查到完整行记录后，会把主键到完整行记录的缓存和索引到主键的缓存同时写到 `redis` 里
+ * 返回所需的行记录数据
+
+```go
+// v - 需要读取的数据对象
+// key - 通过索引生成的缓存key
+// keyer - 用主键生成基于主键缓存的key的方法
+// indexQuery - 用索引从DB读取完整数据的方法，需要返回主键
+// primaryQuery - 用主键从DB获取完整数据的方法
+func (cc CachedConn) QueryRowIndex(v interface{}, key string, keyer func(primary interface{}) string,
+ indexQuery IndexQueryFn, primaryQuery PrimaryQueryFn) error {
+ var primaryKey interface{}
+ var found bool
+
+ // 先通过索引查询缓存，看是否有索引到主键的缓存
+ if err := cc.cache.TakeWithExpire(&primaryKey, key, func(val interface{}, expire time.Duration) (err error) {
+ // 如果没有索引到主键的缓存，那么就通过索引查询完整数据
+ primaryKey, err = indexQuery(cc.db, v)
+ if err != nil {
+ return
+ }
+
+ // 通过索引查询到了完整数据，设置found，后面直接使用，不需要再从缓存读取数据了
+ found = true
+ // 将主键到完整数据的映射保存到缓存里，TakeWithExpire方法已经将索引到主键的映射保存到缓存了
+ return cc.cache.SetCacheWithExpire(keyer(primaryKey), v, expire+cacheSafeGapBetweenIndexAndPrimary)
+ }); err != nil {
+ return err
+ }
+
+ // 已经通过索引找到了数据，直接返回即可
+ if found {
+ return nil
+ }
+
+ // 通过主键从缓存读取数据，如果缓存没有，通过primaryQuery方法从DB读取并回写缓存再返回数据
+ return cc.cache.Take(v, keyer(primaryKey), func(v interface{}) error {
+ return primaryQuery(cc.db, v, primaryKey)
+ })
+}
+```
+
+我们来看一个实际的例子
+```go
+func (m *defaultUserModel) FindOneByUser(user string) (*User, error) {
+ var resp User
+ // 生成基于索引的key
+ indexKey := fmt.Sprintf("%s%v", cacheUserPrefix, user)
+
+ err := m.QueryRowIndex(&resp, indexKey,
+ // 基于主键生成完整数据缓存的key
+ func(primary interface{}) string {
+ return fmt.Sprintf("user#%v", primary)
+ },
+ // 基于索引的DB查询方法
+ func(conn sqlx.SqlConn, v interface{}) (i interface{}, e error) {
+ query := fmt.Sprintf("select %s from %s where user = ? limit 1", userRows, m.table)
+ if err := conn.QueryRow(&resp, query, user); err != nil {
+ return nil, err
+ }
+ return resp.Id, nil
+ },
+ // 基于主键的DB查询方法
+ func(conn sqlx.SqlConn, v, primary interface{}) error {
+ query := fmt.Sprintf("select %s from %s where id = ?", userRows, m.table)
+ return conn.QueryRow(&resp, query, primary)
+ })
+
+ // 错误处理，需要判断是否返回的是sqlc.ErrNotFound，如果是，我们用本package定义的ErrNotFound返回
+ // 避免使用者感知到有没有使用缓存，同时也是对底层依赖的隔离
+ switch err {
+ case nil:
+ return &resp, nil
+ case sqlc.ErrNotFound:
+ return nil, ErrNotFound
+ default:
+ return nil, err
+ }
+}
+```
+
+所有上面这些缓存的自动管理代码都是可以通过 [goctl](goctl.md) 自动生成的，我们团队内部 `CRUD` 和缓存基本都是通过 [goctl](goctl.md) 自动生成的，可以节省大量开发时间，并且缓存代码本身也是非常容易出错的，即使有很好的代码经验，也很难每次完全写对，所以我们推荐尽可能使用自动的缓存代码生成工具去避免错误。
+
+# 猜你想看
+* [Go开源说第四期-go-zero缓存如何设计](https://www.bilibili.com/video/BV1Jy4y127Xu)
+* [Goctl](goctl.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/redis-lock.md b/go-zero.dev/cn/redis-lock.md
new file mode 100644
index 00000000..31890078
--- /dev/null
+++ b/go-zero.dev/cn/redis-lock.md
@@ -0,0 +1,142 @@
+# redis-lock
+
+# redis lock
+
+既然是锁，首先想到的一个作用就是：**防重复点击，在一个时间点只有一个请求产生效果**。
+
+
+而既然是 `redis`，就得具有排他性，同时也具有锁的一些共性：
+
+
+- 高性能
+- 不能出现死锁
+- 不能出现节点down掉后加锁失败
+
+
+
+`go-zero` 中利用 redis `set key nx` 可以保证key不存在时写入成功，`px` 可以让key超时后自动删除「最坏情况也就是超时自动删除key，从而也不会出现死锁」
+
+
+## example
+
+
+```go
+redisLockKey := fmt.Sprintf("%v%v", redisTpl, headId)
+// 1. New redislock
+redisLock := redis.NewRedisLock(redisConn, redisLockKey)
+// 2. 可选操作，设置 redislock 过期时间
+redisLock.SetExpire(redisLockExpireSeconds)
+if ok, err := redisLock.Acquire(); !ok || err != nil {
+ return nil, errors.New("当前有其他用户正在进行操作，请稍后重试")
+}
+defer func() {
+ recover()
+ // 3. 释放锁
+ redisLock.Release()
+}()
+```
+
+
+和你在使用 `sync.Mutex` 的方式时一致的。加锁解锁，执行你的业务操作。
+
+
+## 获取锁
+
+
+```go
+lockCommand = `if redis.call("GET", KEYS[1]) == ARGV[1] then
+ redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[2])
+ return "OK"
+else
+ return redis.call("SET", KEYS[1], ARGV[1], "NX", "PX", ARGV[2])
+end`
+
+func (rl *RedisLock) Acquire() (bool, error) {
+ seconds := atomic.LoadUint32(&rl.seconds)
+ // execute luascript
+ resp, err := rl.store.Eval(lockCommand, []string{rl.key}, []string{
+ rl.id, strconv.Itoa(int(seconds)*millisPerSecond + tolerance)})
+ if err == red.Nil {
+ return false, nil
+ } else if err != nil {
+ logx.Errorf("Error on acquiring lock for %s, %s", rl.key, err.Error())
+ return false, err
+ } else if resp == nil {
+ return false, nil
+ }
+
+ reply, ok := resp.(string)
+ if ok && reply == "OK" {
+ return true, nil
+ } else {
+ logx.Errorf("Unknown reply when acquiring lock for %s: %v", rl.key, resp)
+ return false, nil
+ }
+}
+```
+
+
+先介绍几个 `redis` 的命令选项，以下是为 `set` 命令增加的选项：
+
+
+- `ex seconds` ：设置key过期时间，单位s
+- `px milliseconds` ：设置key过期时间，单位毫秒
+- `nx`：key不存在时，设置key的值
+- `xx`：key存在时，才会去设置key的值
+
+
+
+其中 `lua script` 涉及的入参：
+
+
+
+| args | 示例 | 含义 |
+| --- | --- | --- |
+| KEYS[1] | key$20201026 | redis key |
+| ARGV[1] | lmnopqrstuvwxyzABCD | 唯一标识：随机字符串 |
+| ARGV[2] | 30000 | 设置锁的过期时间 |
+
+
+
+然后来说说代码特性：
+
+
+1. `Lua` 脚本保证原子性「当然，把多个操作在 Redis 中实现成一个操作，也就是单命令操作」
+1. 使用了 `set key value px milliseconds nx`
+1. `value` 具有唯一性
+1. 加锁时首先判断 `key` 的 `value` 是否和之前设置的一致，一致则修改过期时间
+
+
+
+## 释放锁
+
+
+```go
+delCommand = `if redis.call("GET", KEYS[1]) == ARGV[1] then
+ return redis.call("DEL", KEYS[1])
+else
+ return 0
+end`
+
+func (rl *RedisLock) Release() (bool, error) {
+ resp, err := rl.store.Eval(delCommand, []string{rl.key}, []string{rl.id})
+ if err != nil {
+ return false, err
+ }
+
+ if reply, ok := resp.(int64); !ok {
+ return false, nil
+ } else {
+ return reply == 1, nil
+ }
+}
+```
+
+
+释放锁的时候只需要关注一点：
+
+
+**不能释放别人的锁，不能释放别人的锁，不能释放别人的锁**
+
+
+所以需要先 `get(key) == value「key」`，为 true 才会去 `delete`
diff --git a/go-zero.dev/cn/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png b/go-zero.dev/cn/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png
new file mode 100644
index 00000000..603f8a97
Binary files /dev/null and b/go-zero.dev/cn/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png differ
diff --git a/go-zero.dev/cn/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png b/go-zero.dev/cn/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png
new file mode 100644
index 00000000..f530f572
Binary files /dev/null and b/go-zero.dev/cn/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png differ
diff --git a/go-zero.dev/cn/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png b/go-zero.dev/cn/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png
new file mode 100644
index 00000000..42bdbd1c
Binary files /dev/null and b/go-zero.dev/cn/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png differ
diff --git a/go-zero.dev/cn/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png b/go-zero.dev/cn/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png
new file mode 100644
index 00000000..4513c5ac
Binary files /dev/null and b/go-zero.dev/cn/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png differ
diff --git a/go-zero.dev/cn/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png b/go-zero.dev/cn/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png
new file mode 100644
index 00000000..37e6fe93
Binary files /dev/null and b/go-zero.dev/cn/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png differ
diff --git a/go-zero.dev/cn/resource/Thumbs.db b/go-zero.dev/cn/resource/Thumbs.db
new file mode 100644
index 00000000..9bd677dc
Binary files /dev/null and b/go-zero.dev/cn/resource/Thumbs.db differ
diff --git a/go-zero.dev/cn/resource/alert.png b/go-zero.dev/cn/resource/alert.png
new file mode 100644
index 00000000..f24580d3
Binary files /dev/null and b/go-zero.dev/cn/resource/alert.png differ
diff --git a/go-zero.dev/cn/resource/api-compare.png b/go-zero.dev/cn/resource/api-compare.png
new file mode 100644
index 00000000..eb083a0a
Binary files /dev/null and b/go-zero.dev/cn/resource/api-compare.png differ
diff --git a/go-zero.dev/cn/resource/api-new.png b/go-zero.dev/cn/resource/api-new.png
new file mode 100644
index 00000000..469a8cd0
Binary files /dev/null and b/go-zero.dev/cn/resource/api-new.png differ
diff --git a/go-zero.dev/cn/resource/architechture.svg b/go-zero.dev/cn/resource/architechture.svg
new file mode 100644
index 00000000..161e1262
--- /dev/null
+++ b/go-zero.dev/cn/resource/architechture.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/go-zero.dev/cn/resource/author.jpeg b/go-zero.dev/cn/resource/author.jpeg
new file mode 100644
index 00000000..c566910a
Binary files /dev/null and b/go-zero.dev/cn/resource/author.jpeg differ
diff --git a/go-zero.dev/cn/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png b/go-zero.dev/cn/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png
new file mode 100644
index 00000000..4e4455a3
Binary files /dev/null and b/go-zero.dev/cn/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png differ
diff --git a/go-zero.dev/cn/resource/biz-redis-01.svg b/go-zero.dev/cn/resource/biz-redis-01.svg
new file mode 100644
index 00000000..95e80f43
--- /dev/null
+++ b/go-zero.dev/cn/resource/biz-redis-01.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/go-zero.dev/cn/resource/biz-redis-02.svg b/go-zero.dev/cn/resource/biz-redis-02.svg
new file mode 100644
index 00000000..acf355e1
--- /dev/null
+++ b/go-zero.dev/cn/resource/biz-redis-02.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/go-zero.dev/cn/resource/book.zip b/go-zero.dev/cn/resource/book.zip
new file mode 100644
index 00000000..a62c7bcd
Binary files /dev/null and b/go-zero.dev/cn/resource/book.zip differ
diff --git a/go-zero.dev/cn/resource/breaker_state.png b/go-zero.dev/cn/resource/breaker_state.png
new file mode 100644
index 00000000..73ce5141
Binary files /dev/null and b/go-zero.dev/cn/resource/breaker_state.png differ
diff --git a/go-zero.dev/cn/resource/c42c34e8d33d48ec8a63e56feeae882a.png b/go-zero.dev/cn/resource/c42c34e8d33d48ec8a63e56feeae882a.png
new file mode 100644
index 00000000..1fdebc4b
Binary files /dev/null and b/go-zero.dev/cn/resource/c42c34e8d33d48ec8a63e56feeae882a.png differ
diff --git a/go-zero.dev/cn/resource/call_chain.png b/go-zero.dev/cn/resource/call_chain.png
new file mode 100644
index 00000000..6a96a75a
Binary files /dev/null and b/go-zero.dev/cn/resource/call_chain.png differ
diff --git a/go-zero.dev/cn/resource/ci-cd.png b/go-zero.dev/cn/resource/ci-cd.png
new file mode 100644
index 00000000..ee16b01e
Binary files /dev/null and b/go-zero.dev/cn/resource/ci-cd.png differ
diff --git a/go-zero.dev/cn/resource/client_rejection2.png b/go-zero.dev/cn/resource/client_rejection2.png
new file mode 100644
index 00000000..11373680
Binary files /dev/null and b/go-zero.dev/cn/resource/client_rejection2.png differ
diff --git a/go-zero.dev/cn/resource/clone.png b/go-zero.dev/cn/resource/clone.png
new file mode 100644
index 00000000..e463d566
Binary files /dev/null and b/go-zero.dev/cn/resource/clone.png differ
diff --git a/go-zero.dev/cn/resource/compare.png b/go-zero.dev/cn/resource/compare.png
new file mode 100644
index 00000000..42216ae3
Binary files /dev/null and b/go-zero.dev/cn/resource/compare.png differ
diff --git a/go-zero.dev/cn/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png b/go-zero.dev/cn/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png
new file mode 100644
index 00000000..716ea11d
Binary files /dev/null and b/go-zero.dev/cn/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png differ
diff --git a/go-zero.dev/cn/resource/doc-edit.png b/go-zero.dev/cn/resource/doc-edit.png
new file mode 100644
index 00000000..14b9eb10
Binary files /dev/null and b/go-zero.dev/cn/resource/doc-edit.png differ
diff --git a/go-zero.dev/cn/resource/docker_env.png b/go-zero.dev/cn/resource/docker_env.png
new file mode 100644
index 00000000..5ac04759
Binary files /dev/null and b/go-zero.dev/cn/resource/docker_env.png differ
diff --git a/go-zero.dev/cn/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png b/go-zero.dev/cn/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png
new file mode 100644
index 00000000..afcde0fb
Binary files /dev/null and b/go-zero.dev/cn/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png differ
diff --git a/go-zero.dev/cn/resource/fork.png b/go-zero.dev/cn/resource/fork.png
new file mode 100644
index 00000000..44521bb3
Binary files /dev/null and b/go-zero.dev/cn/resource/fork.png differ
diff --git a/go-zero.dev/cn/resource/fx_log.png b/go-zero.dev/cn/resource/fx_log.png
new file mode 100644
index 00000000..45ca95e6
Binary files /dev/null and b/go-zero.dev/cn/resource/fx_log.png differ
diff --git a/go-zero.dev/cn/resource/gitlab-git-url.png b/go-zero.dev/cn/resource/gitlab-git-url.png
new file mode 100644
index 00000000..b2ed854a
Binary files /dev/null and b/go-zero.dev/cn/resource/gitlab-git-url.png differ
diff --git a/go-zero.dev/cn/resource/go-zero-logo.png b/go-zero.dev/cn/resource/go-zero-logo.png
new file mode 100644
index 00000000..a0ec1cd5
Binary files /dev/null and b/go-zero.dev/cn/resource/go-zero-logo.png differ
diff --git a/go-zero.dev/cn/resource/go-zero-practise.png b/go-zero.dev/cn/resource/go-zero-practise.png
new file mode 100755
index 00000000..0be4da53
Binary files /dev/null and b/go-zero.dev/cn/resource/go-zero-practise.png differ
diff --git a/go-zero.dev/cn/resource/go_live_template.png b/go-zero.dev/cn/resource/go_live_template.png
new file mode 100644
index 00000000..28110974
Binary files /dev/null and b/go-zero.dev/cn/resource/go_live_template.png differ
diff --git a/go-zero.dev/cn/resource/goctl-api-select.png b/go-zero.dev/cn/resource/goctl-api-select.png
new file mode 100644
index 00000000..d852489f
Binary files /dev/null and b/go-zero.dev/cn/resource/goctl-api-select.png differ
diff --git a/go-zero.dev/cn/resource/goctl-api.png b/go-zero.dev/cn/resource/goctl-api.png
new file mode 100644
index 00000000..83a5cf48
Binary files /dev/null and b/go-zero.dev/cn/resource/goctl-api.png differ
diff --git a/go-zero.dev/cn/resource/goctl-command.png b/go-zero.dev/cn/resource/goctl-command.png
new file mode 100644
index 00000000..6f38d223
Binary files /dev/null and b/go-zero.dev/cn/resource/goctl-command.png differ
diff --git a/go-zero.dev/cn/resource/grafana-app.png b/go-zero.dev/cn/resource/grafana-app.png
new file mode 100644
index 00000000..aa97e4d5
Binary files /dev/null and b/go-zero.dev/cn/resource/grafana-app.png differ
diff --git a/go-zero.dev/cn/resource/grafana-panel.png b/go-zero.dev/cn/resource/grafana-panel.png
new file mode 100644
index 00000000..b82430c5
Binary files /dev/null and b/go-zero.dev/cn/resource/grafana-panel.png differ
diff --git a/go-zero.dev/cn/resource/grafana-qps.png b/go-zero.dev/cn/resource/grafana-qps.png
new file mode 100644
index 00000000..14a86dd5
Binary files /dev/null and b/go-zero.dev/cn/resource/grafana-qps.png differ
diff --git a/go-zero.dev/cn/resource/grafana.png b/go-zero.dev/cn/resource/grafana.png
new file mode 100644
index 00000000..0c648728
Binary files /dev/null and b/go-zero.dev/cn/resource/grafana.png differ
diff --git a/go-zero.dev/cn/resource/handler.gif b/go-zero.dev/cn/resource/handler.gif
new file mode 100644
index 00000000..fd1c1c38
Binary files /dev/null and b/go-zero.dev/cn/resource/handler.gif differ
diff --git a/go-zero.dev/cn/resource/info.gif b/go-zero.dev/cn/resource/info.gif
new file mode 100644
index 00000000..f4c26bf5
Binary files /dev/null and b/go-zero.dev/cn/resource/info.gif differ
diff --git a/go-zero.dev/cn/resource/intellij-model.png b/go-zero.dev/cn/resource/intellij-model.png
new file mode 100644
index 00000000..66dd40ad
Binary files /dev/null and b/go-zero.dev/cn/resource/intellij-model.png differ
diff --git a/go-zero.dev/cn/resource/interceptor.png b/go-zero.dev/cn/resource/interceptor.png
new file mode 100644
index 00000000..c4899132
Binary files /dev/null and b/go-zero.dev/cn/resource/interceptor.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-add-credentials.png b/go-zero.dev/cn/resource/jenkins-add-credentials.png
new file mode 100644
index 00000000..e5dc389d
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-add-credentials.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-build-with-parameters.png b/go-zero.dev/cn/resource/jenkins-build-with-parameters.png
new file mode 100644
index 00000000..14684389
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-build-with-parameters.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-choice.png b/go-zero.dev/cn/resource/jenkins-choice.png
new file mode 100644
index 00000000..c86e722a
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-choice.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-configure.png b/go-zero.dev/cn/resource/jenkins-configure.png
new file mode 100644
index 00000000..69a0b430
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-configure.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-credentials-id.png b/go-zero.dev/cn/resource/jenkins-credentials-id.png
new file mode 100644
index 00000000..2f633628
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-credentials-id.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-credentials.png b/go-zero.dev/cn/resource/jenkins-credentials.png
new file mode 100644
index 00000000..372b9262
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-credentials.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-git.png b/go-zero.dev/cn/resource/jenkins-git.png
new file mode 100644
index 00000000..950fc5b6
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-git.png differ
diff --git a/go-zero.dev/cn/resource/jenkins-new-item.png b/go-zero.dev/cn/resource/jenkins-new-item.png
new file mode 100644
index 00000000..4ad817b6
Binary files /dev/null and b/go-zero.dev/cn/resource/jenkins-new-item.png differ
diff --git a/go-zero.dev/cn/resource/json_tag.png b/go-zero.dev/cn/resource/json_tag.png
new file mode 100644
index 00000000..e8f44c9c
Binary files /dev/null and b/go-zero.dev/cn/resource/json_tag.png differ
diff --git a/go-zero.dev/cn/resource/jump.gif b/go-zero.dev/cn/resource/jump.gif
new file mode 100644
index 00000000..8581aae5
Binary files /dev/null and b/go-zero.dev/cn/resource/jump.gif differ
diff --git a/go-zero.dev/cn/resource/k8s-01.png b/go-zero.dev/cn/resource/k8s-01.png
new file mode 100644
index 00000000..9192926a
Binary files /dev/null and b/go-zero.dev/cn/resource/k8s-01.png differ
diff --git a/go-zero.dev/cn/resource/k8s-02.png b/go-zero.dev/cn/resource/k8s-02.png
new file mode 100644
index 00000000..2ec67d6d
Binary files /dev/null and b/go-zero.dev/cn/resource/k8s-02.png differ
diff --git a/go-zero.dev/cn/resource/k8s-03.png b/go-zero.dev/cn/resource/k8s-03.png
new file mode 100644
index 00000000..e672db3a
Binary files /dev/null and b/go-zero.dev/cn/resource/k8s-03.png differ
diff --git a/go-zero.dev/cn/resource/live_template.gif b/go-zero.dev/cn/resource/live_template.gif
new file mode 100644
index 00000000..dac3499e
Binary files /dev/null and b/go-zero.dev/cn/resource/live_template.gif differ
diff --git a/go-zero.dev/cn/resource/log-flow.png b/go-zero.dev/cn/resource/log-flow.png
new file mode 100644
index 00000000..2421ddce
Binary files /dev/null and b/go-zero.dev/cn/resource/log-flow.png differ
diff --git a/go-zero.dev/cn/resource/log.png b/go-zero.dev/cn/resource/log.png
new file mode 100644
index 00000000..9c751d7e
Binary files /dev/null and b/go-zero.dev/cn/resource/log.png differ
diff --git a/go-zero.dev/cn/resource/logo.png b/go-zero.dev/cn/resource/logo.png
new file mode 100644
index 00000000..16798ee5
Binary files /dev/null and b/go-zero.dev/cn/resource/logo.png differ
diff --git a/go-zero.dev/cn/resource/new_pr.png b/go-zero.dev/cn/resource/new_pr.png
new file mode 100644
index 00000000..02d38b9f
Binary files /dev/null and b/go-zero.dev/cn/resource/new_pr.png differ
diff --git a/go-zero.dev/cn/resource/pipeline.png b/go-zero.dev/cn/resource/pipeline.png
new file mode 100644
index 00000000..eb51eaec
Binary files /dev/null and b/go-zero.dev/cn/resource/pipeline.png differ
diff --git a/go-zero.dev/cn/resource/pr_record.png b/go-zero.dev/cn/resource/pr_record.png
new file mode 100644
index 00000000..8b0e4937
Binary files /dev/null and b/go-zero.dev/cn/resource/pr_record.png differ
diff --git a/go-zero.dev/cn/resource/project_generate_code.png b/go-zero.dev/cn/resource/project_generate_code.png
new file mode 100644
index 00000000..a637403b
Binary files /dev/null and b/go-zero.dev/cn/resource/project_generate_code.png differ
diff --git a/go-zero.dev/cn/resource/prometheus-flow.png b/go-zero.dev/cn/resource/prometheus-flow.png
new file mode 100644
index 00000000..ce6a97af
Binary files /dev/null and b/go-zero.dev/cn/resource/prometheus-flow.png differ
diff --git a/go-zero.dev/cn/resource/prometheus-graph.webp b/go-zero.dev/cn/resource/prometheus-graph.webp
new file mode 100644
index 00000000..d283fc5a
Binary files /dev/null and b/go-zero.dev/cn/resource/prometheus-graph.webp differ
diff --git a/go-zero.dev/cn/resource/prometheus-start.png b/go-zero.dev/cn/resource/prometheus-start.png
new file mode 100644
index 00000000..ee0bbefa
Binary files /dev/null and b/go-zero.dev/cn/resource/prometheus-start.png differ
diff --git a/go-zero.dev/cn/resource/psiTree.png b/go-zero.dev/cn/resource/psiTree.png
new file mode 100644
index 00000000..06af982a
Binary files /dev/null and b/go-zero.dev/cn/resource/psiTree.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-01.png b/go-zero.dev/cn/resource/redis-cache-01.png
new file mode 100644
index 00000000..f07a1133
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-01.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-02.png b/go-zero.dev/cn/resource/redis-cache-02.png
new file mode 100644
index 00000000..ba8f2fb0
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-02.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-03.png b/go-zero.dev/cn/resource/redis-cache-03.png
new file mode 100644
index 00000000..8b2449a8
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-03.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-04.png b/go-zero.dev/cn/resource/redis-cache-04.png
new file mode 100644
index 00000000..38b3f0f4
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-04.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-05.png b/go-zero.dev/cn/resource/redis-cache-05.png
new file mode 100644
index 00000000..4a743ec7
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-05.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-06.png b/go-zero.dev/cn/resource/redis-cache-06.png
new file mode 100644
index 00000000..ec9cf88f
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-06.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-07.png b/go-zero.dev/cn/resource/redis-cache-07.png
new file mode 100644
index 00000000..c84d292d
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-07.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-08.png b/go-zero.dev/cn/resource/redis-cache-08.png
new file mode 100644
index 00000000..039816e4
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-08.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-09.webp b/go-zero.dev/cn/resource/redis-cache-09.webp
new file mode 100644
index 00000000..e13122b6
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-09.webp differ
diff --git a/go-zero.dev/cn/resource/redis-cache-10.png b/go-zero.dev/cn/resource/redis-cache-10.png
new file mode 100644
index 00000000..ec8e69a3
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-10.png differ
diff --git a/go-zero.dev/cn/resource/redis-cache-11.webp b/go-zero.dev/cn/resource/redis-cache-11.webp
new file mode 100644
index 00000000..5476baf0
Binary files /dev/null and b/go-zero.dev/cn/resource/redis-cache-11.webp differ
diff --git a/go-zero.dev/cn/resource/service.gif b/go-zero.dev/cn/resource/service.gif
new file mode 100644
index 00000000..dbf7f613
Binary files /dev/null and b/go-zero.dev/cn/resource/service.gif differ
diff --git a/go-zero.dev/cn/resource/service.png b/go-zero.dev/cn/resource/service.png
new file mode 100644
index 00000000..09b51d7f
Binary files /dev/null and b/go-zero.dev/cn/resource/service.png differ
diff --git a/go-zero.dev/cn/resource/ssh-add-key.png b/go-zero.dev/cn/resource/ssh-add-key.png
new file mode 100644
index 00000000..70635b7e
Binary files /dev/null and b/go-zero.dev/cn/resource/ssh-add-key.png differ
diff --git a/go-zero.dev/cn/resource/type.gif b/go-zero.dev/cn/resource/type.gif
new file mode 100644
index 00000000..e4d4d7a1
Binary files /dev/null and b/go-zero.dev/cn/resource/type.gif differ
diff --git a/go-zero.dev/cn/resource/user-pipeline-script.png b/go-zero.dev/cn/resource/user-pipeline-script.png
new file mode 100644
index 00000000..57ede338
Binary files /dev/null and b/go-zero.dev/cn/resource/user-pipeline-script.png differ
diff --git a/go-zero.dev/cn/route-naming-spec.md b/go-zero.dev/cn/route-naming-spec.md
new file mode 100644
index 00000000..53259d70
--- /dev/null
+++ b/go-zero.dev/cn/route-naming-spec.md
@@ -0,0 +1,10 @@
+# 路由规范
+* 推荐脊柱式命名
+* 小写单词、横杠(-)组合
+* 见名知义
+
+```go
+/user/get-info
+/user/get/info
+/user/password/change/:id
+```
\ No newline at end of file
diff --git a/go-zero.dev/cn/rpc-call.md b/go-zero.dev/cn/rpc-call.md
new file mode 100644
index 00000000..1245d433
--- /dev/null
+++ b/go-zero.dev/cn/rpc-call.md
@@ -0,0 +1,252 @@
+# rpc编写与调用
+在一个大的系统中，多个子系统（服务）间必然存在数据传递，有数据传递就需要通信方式，你可以选择最简单的http进行通信，也可以选择rpc服务进行通信，
+在go-zero，我们使用zrpc来进行服务间的通信，zrpc是基于grpc。
+
+## 场景
+在前面我们完善了对用户进行登录，用户查询图书等接口协议，但是用户在查询图书时没有做任何用户校验，如果当前用户是一个不存在的用户则我们不允许其查阅图书信息，
+从上文信息我们可以得知，需要user服务提供一个方法来获取用户信息供search服务使用，因此我们就需要创建一个user rpc服务，并提供一个getUser方法。
+
+## rpc服务编写
+
+* 编译proto文件
+ ```shell
+ $ vim service/user/cmd/rpc/user.proto
+ ```
+ ```protobuf
+ syntax = "proto3";
+
+ package user;
+
+ option go_package = "user";
+
+ message IdReq{
+ int64 id = 1;
+ }
+
+ message UserInfoReply{
+ int64 id = 1;
+ string name = 2;
+ string number = 3;
+ string gender = 4;
+ }
+
+ service user {
+ rpc getUser(IdReq) returns(UserInfoReply);
+ }
+ ```
+ * 生成rpc服务代码
+ ```shell
+ $ cd service/user/cmd/rpc
+ $ goctl rpc proto -src user.proto -dir .
+ ```
+> [!TIPS]
+> 如果安装的 `protoc-gen-go` 版大于1.4.0, proto文件建议加上`go_package`
+
+* 添加配置及完善yaml配置项
+ ```shell
+ $ vim service/user/cmd/rpc/internal/config/config.go
+ ```
+ ```go
+ type Config struct {
+ zrpc.RpcServerConf
+ Mysql struct {
+ DataSource string
+ }
+ CacheRedis cache.CacheConf
+ }
+ ```
+ ```shell
+ $ vim /service/user/cmd/rpc/etc/user.yaml
+ ```
+ ```yaml
+ Name: user.rpc
+ ListenOn: 127.0.0.1:8080
+ Etcd:
+ Hosts:
+ - $etcdHost
+ Key: user.rpc
+ Mysql:
+ DataSource: $user:$password@tcp($url)/$db?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+ CacheRedis:
+ - Host: $host
+ Pass: $pass
+ Type: node
+ ```
+ > [!TIP]
+ > $user: mysql数据库user
+ >
+ > $password: mysql数据库密码
+ >
+ > $url: mysql数据库连接地址
+ >
+ > $db: mysql数据库db名称，即user表所在database
+ >
+ > $host: redis连接地址 格式：ip:port，如:127.0.0.1:6379
+ >
+ > $pass: redis密码
+ >
+ > $etcdHost: etcd连接地址，格式：ip:port，如： 127.0.0.1:2379
+ >
+ > 更多配置信息，请参考[rpc配置介绍](rpc-config.md)
+
+* 添加资源依赖
+ ```shell
+ $ vim service/user/cmd/rpc/internal/svc/servicecontext.go
+ ```
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ UserModel model.UserModel
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ conn := sqlx.NewMysql(c.Mysql.DataSource)
+ return &ServiceContext{
+ Config: c,
+ UserModel: model.NewUserModel(conn, c.CacheRedis),
+ }
+ }
+ ```
+* 添加rpc逻辑
+ ```shell
+ $ service/user/cmd/rpc/internal/logic/getuserlogic.go
+ ```
+ ```go
+ func (l *GetUserLogic) GetUser(in *user.IdReq) (*user.UserInfoReply, error) {
+ one, err := l.svcCtx.UserModel.FindOne(in.Id)
+ if err != nil {
+ return nil, err
+ }
+
+ return &user.UserInfoReply{
+ Id: one.Id,
+ Name: one.Name,
+ Number: one.Number,
+ Gender: one.Gender,
+ }, nil
+ }
+ ```
+
+## 使用rpc
+接下来我们在search服务中调用user rpc
+
+* 添加UserRpc配置及yaml配置项
+ ```shell
+ $ vim service/search/cmd/api/internal/config/config.go
+ ```
+ ```go
+ type Config struct {
+ rest.RestConf
+ Auth struct {
+ AccessSecret string
+ AccessExpire int64
+ }
+ UserRpc zrpc.RpcClientConf
+ }
+ ```
+ ```shell
+ $ vim service/search/cmd/api/etc/search-api.yaml
+ ```
+ ```yaml
+ Name: search-api
+ Host: 0.0.0.0
+ Port: 8889
+ Auth:
+ AccessSecret: $AccessSecret
+ AccessExpire: $AccessExpire
+ UserRpc:
+ Etcd:
+ Hosts:
+ - $etcdHost
+ Key: user.rpc
+ ```
+ > [!TIP]
+ > $AccessSecret：这个值必须要和user api中声明的一致。
+ >
+ > $AccessExpire: 有效期
+ >
+ > $etcdHost： etcd连接地址
+ >
+ > etcd中的`Key`必须要和user rpc服务配置中Key一致
+* 添加依赖
+ ```shell
+ $ vim service/search/cmd/api/internal/svc/servicecontext.go
+ ```
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ Example rest.Middleware
+ UserRpc userclient.User
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ Example: middleware.NewExampleMiddleware().Handle,
+ UserRpc: userclient.NewUser(zrpc.MustNewClient(c.UserRpc)),
+ }
+ }
+ ```
+* 补充逻辑
+ ```shell
+ $ vim /service/search/cmd/api/internal/logic/searchlogic.go
+ ```
+ ```go
+ func (l *SearchLogic) Search(req types.SearchReq) (*types.SearchReply, error) {
+ userIdNumber := json.Number(fmt.Sprintf("%v", l.ctx.Value("userId")))
+ logx.Infof("userId: %s", userIdNumber)
+ userId, err := userIdNumber.Int64()
+ if err != nil {
+ return nil, err
+ }
+
+ // 使用user rpc
+ _, err = l.svcCtx.UserRpc.GetUser(l.ctx, &userclient.IdReq{
+ Id: userId,
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ return &types.SearchReply{
+ Name: req.Name,
+ Count: 100,
+ }, nil
+ }
+ ```
+## 启动并验证服务
+* 启动etcd、redis、mysql
+* 启动user rpc
+ ```shell
+ $ cd /service/user/cmd/rpc
+ $ go run user.go -f etc/user.yaml
+ ```
+ ```text
+ Starting rpc server at 127.0.0.1:8080...
+ ```
+* 启动search api
+```shell
+$ cd service/search/cmd/api
+$ go run search.go -f etc/search-api.yaml
+```
+
+* 验证服务
+ ```shell
+ $ curl -i -X GET \
+ 'http://127.0.0.1:8889/search/do?name=%E8%A5%BF%E6%B8%B8%E8%AE%B0' \
+ -H 'authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NjcwNzQsImlhdCI6MTYxMjc4MDY3NCwidXNlcklkIjoxfQ.JKa83g9BlEW84IiCXFGwP2aSd0xF3tMnxrOzVebbt80'
+ ```
+ ```text
+ HTTP/1.1 200 OK
+ Content
+ -Type: application/json
+ Date: Tue, 09 Feb 2021 06:05:52 GMT
+ Content-Length: 32
+
+ {"name":"西游记","count":100}
+ ```
+
+# 猜你想看
+* [rpc配置](rpc-config.md)
+* [rpc服务目录](rpc-dir.md)
+* [goctl rpc命令](goctl-rpc.md)
diff --git a/go-zero.dev/cn/rpc-config.md b/go-zero.dev/cn/rpc-config.md
new file mode 100644
index 00000000..8836b878
--- /dev/null
+++ b/go-zero.dev/cn/rpc-config.md
@@ -0,0 +1,52 @@
+# rpc配置
+
+rpc配置控制着一个rpc服务的各种功能，包含但不限于监听地址，etcd配置，超时，熔断配置等，下面我们以一个常见的rpc服务配置来进行说明。
+
+## 配置说明
+```go
+Config struct {
+ zrpc.RpcServerConf
+ CacheRedis cache.CacheConf // redis缓存配置，详情见api配置说明，这里不赘述
+ Mysql struct { // mysql数据库访问配置，详情见api配置说明，这里不赘述
+ DataSource string
+ }
+}
+```
+
+### zrpc.RpcServerConf
+```go
+RpcServerConf struct {
+ service.ServiceConf // 服务配置，详情见api配置说明，这里不赘述
+ ListenOn string // rpc监听地址和端口，如：127.0.0.1:8888
+ Etcd discov.EtcdConf `json:",optional"` // etcd相关配置
+ Auth bool `json:",optional"` // 是否开启Auth，如果是则Redis为必填
+ Redis redis.RedisKeyConf `json:",optional"` // Auth验证
+ StrictControl bool `json:",optional"` // 是否Strict模式，如果是则遇到错误是Auth失败，否则可以认为成功
+ // pending forever is not allowed
+ // never set it to 0, if zero, the underlying will set to 2s automatically
+ Timeout int64 `json:",default=2000"` // 超时控制，单位：毫秒
+ CpuThreshold int64 `json:",default=900,range=[0:1000]"` cpu降载阈值，默认900，可允许设置范围0到1000
+}
+```
+
+### discov.EtcdConf
+```go
+type EtcdConf struct {
+ Hosts []string // etcd host数组
+ Key string // rpc注册key
+}
+```
+
+### redis.RedisKeyConf
+```go
+RedisConf struct {
+ Host string // redis 主机
+ Type string `json:",default=node,options=node|cluster"` // redis类型
+ Pass string `json:",optional"` // redis密码
+}
+
+RedisKeyConf struct {
+ RedisConf
+ Key string `json:",optional"` // 验证key
+}
+```
diff --git a/go-zero.dev/cn/rpc-dir.md b/go-zero.dev/cn/rpc-dir.md
new file mode 100644
index 00000000..e8641673
--- /dev/null
+++ b/go-zero.dev/cn/rpc-dir.md
@@ -0,0 +1,49 @@
+# rpc服务目录
+
+```text
+.
+├── etc // yaml配置文件
+│ └── greet.yaml
+├── go.mod
+├── greet // pb.go文件夹①
+│ └── greet.pb.go
+├── greet.go // main函数
+├── greet.proto // proto 文件
+├── greetclient // call logic ②
+│ └── greet.go
+└── internal
+ ├── config // yaml配置对应的实体
+ │ └── config.go
+ ├── logic // 业务代码
+ │ └── pinglogic.go
+ ├── server // rpc server
+ │ └── greetserver.go
+ └── svc // 依赖资源
+ └── servicecontext.go
+```
+
+> [!TIP]
+> ① pb文件夹名（老版本文件夹固定为pb）称取自于proto文件中option go_package的值最后一层级按照一定格式进行转换，若无此声明，则取自于package的值，大致代码如下：
+
+```go
+ if option.Name == "go_package" {
+ ret.GoPackage = option.Constant.Source
+ }
+ ...
+ if len(ret.GoPackage) == 0 {
+ ret.GoPackage = ret.Package.Name
+ }
+ ret.PbPackage = GoSanitized(filepath.Base(ret.GoPackage))
+ ...
+```
+> [!TIP]
+> GoSanitized方法请参考google.golang.org/protobuf@v1.25.0/internal/strs/strings.go:71
+
+> [!TIP]
+> ② call 层文件夹名称取自于proto中service的名称，如该sercice的名称和pb文件夹名称相等，则会在srervice后面补充client进行区分，使pb和call分隔。
+
+```go
+if strings.ToLower(proto.Service.Name) == strings.ToLower(proto.GoPackage) {
+ callDir = filepath.Join(ctx.WorkDir, strings.ToLower(stringx.From(proto.Service.Name+"_client").ToCamel()))
+}
+```
\ No newline at end of file
diff --git a/go-zero.dev/cn/service-deployment.md b/go-zero.dev/cn/service-deployment.md
new file mode 100644
index 00000000..b411d5be
--- /dev/null
+++ b/go-zero.dev/cn/service-deployment.md
@@ -0,0 +1,241 @@
+# 服务部署
+本节通过jenkins来进行简单的服务部署到k8s演示。
+
+## 准备工作
+* k8s集群安装
+* gitlab环境安装
+* jenkins环境安装
+* redis&mysql&nginx&etcd安装
+* [goctl安装](goctl-install.md)
+
+> [!TIP]
+> goctl确保k8s每个node节点上都有
+>
+> 以上环境安装请自行google，这里不做篇幅介绍。
+
+## 服务部署
+### 1、gitlab代码仓库相关准备
+
+#### 1.1、添加SSH Key
+
+进入gitlab，点击用户中心，找到`Settings`，在左侧找到`SSH Keys`tab
+
+
+* 1、在jenkins所在机器上查看公钥
+
+```shell
+$ cat ~/.ssh/id_rsa.pub
+```
+
+* 2、如果没有，则需要生成，如果存在，请跳转到第3步
+
+```shell
+$ ssh-keygen -t rsa -b 2048 -C "email@example.com"
+```
+
+> "email@example.com" 可以替换为自己的邮箱
+>
+完成生成后，重复第一步操作
+
+* 3、将公钥添加到gitlab中
+
+#### 1.2、上传代码到gitlab仓库
+新建工程`go-zero-demo`并上传代码，这里不做细节描述。
+
+### 2、jenkins
+
+#### 2.1、添加凭据
+
+* 查看jenkins所在机器的私钥，与前面gitlab公钥对应
+
+```shell
+$ cat id_rsa
+```
+
+* 进入jenkins，依次点击`Manage Jenkins`-> `Manage Credentials`
+ 
+
+* 进入`全局凭据`页面，添加凭据，`Username`是一个标识，后面添加pipeline你知道这个标识是代表gitlab的凭据就行，Private Key`即上面获取的私钥
+ 
+
+#### 2.2、 添加全局变量
+进入`Manage Jenkins`->`Configure System`，滑动到`全局属性`条目，添加docker私有仓库相关信息，如图为`docker用户名`、`docker用户密码`、`docker私有仓库地址`
+
+
+> [!TIP]
+>
+> `docker_user` 修改为你的docker用户名
+>
+> `docker_pass` 修改为你的docker用户密码
+>
+> `docker_server` 修改为你的docker服务器地址
+>
+> 这里我使用的私有仓库，如果没有云厂商提供的私有仓库使用，可以自行搭建一个私有仓库，这里就不赘述了，大家自行google。
+
+#### 2.3、配置git
+进入`Manage Jenkins`->`Global Tool Configureation`，找到Git条目，填写jenkins所在机器git可执行文件所在path，如果没有的话，需要在jenkins插件管理中下载Git插件。
+
+
+
+
+#### 2.4、 添加一个Pipeline
+
+> pipeline用于构建项目，从gitlab拉取代码->生成Dockerfile->部署到k8s均在这个步骤去做，这里是演示环境，为了保证部署流程顺利，
+> 需要将jenkins安装在和k8s集群的其中过一个节点所在机器上，我这里安装在master上的。
+
+* 获取凭据id 进入凭据页面，找到Username为`gitlab`的凭据id
+ 
+
+* 进入jenkins首页，点击`新建Item`，名称为`user`
+ 
+
+* 查看项目git地址
+ 
+
+* 添加服务类型Choice Parameter,在General中勾选`This project is parameterized
+ `,点击`添加参数`选择`Choice Parameter`，按照图中添加选择的值常量(api、rpc)及接收值的变量(type)，后续在Pipeline script中会用到。
+ 
+
+* 配置`user`，在`user`配置页面，向下滑动找到`Pipeline script`,填写脚本内容
+
+```text
+pipeline {
+ agent any
+ parameters {
+ gitParameter name: 'branch',
+ type: 'PT_BRANCH',
+ branchFilter: 'origin/(.*)',
+ defaultValue: 'master',
+ selectedValue: 'DEFAULT',
+ sortMode: 'ASCENDING_SMART',
+ description: '选择需要构建的分支'
+ }
+
+ stages {
+ stage('服务信息') {
+ steps {
+ sh 'echo 分支：$branch'
+ sh 'echo 构建服务类型：${JOB_NAME}-$type'
+ }
+ }
+
+
+ stage('check out') {
+ steps {
+ checkout([$class: 'GitSCM',
+ branches: [[name: '$branch']],
+ doGenerateSubmoduleConfigurations: false,
+ extensions: [],
+ submoduleCfg: [],
+ userRemoteConfigs: [[credentialsId: '${credentialsId}', url: '${gitUrl}']]])
+ }
+ }
+
+ stage('获取commit_id') {
+ steps {
+ echo '获取commit_id'
+ git credentialsId: '${credentialsId}', url: '${gitUrl}'
+ script {
+ env.commit_id = sh(returnStdout: true, script: 'git rev-parse --short HEAD').trim()
+ }
+ }
+ }
+
+
+ stage('goctl版本检测') {
+ steps{
+ sh '/usr/local/bin/goctl -v'
+ }
+ }
+
+ stage('Dockerfile Build') {
+ steps{
+ sh '/usr/local/bin/goctl docker -go service/${JOB_NAME}/${type}/${JOB_NAME}.go'
+ script{
+ env.image = sh(returnStdout: true, script: 'echo ${JOB_NAME}-${type}:${commit_id}').trim()
+ }
+ sh 'echo 镜像名称：${image}'
+ sh 'docker build -t ${image} .'
+ }
+ }
+
+ stage('上传到镜像仓库') {
+ steps{
+ sh '/root/dockerlogin.sh'
+ sh 'docker tag ${image} ${dockerServer}/${image}'
+ sh 'docker push ${dockerServer}/${image}'
+ }
+ }
+
+ stage('部署到k8s') {
+ steps{
+ script{
+ env.deployYaml = sh(returnStdout: true, script: 'echo ${JOB_NAME}-${type}-deploy.yaml').trim()
+ env.port=sh(returnStdout: true, script: '/root/port.sh ${JOB_NAME}-${type}').trim()
+ }
+
+ sh 'echo ${port}'
+
+ sh 'rm -f ${deployYaml}'
+ sh '/usr/local/bin/goctl kube deploy -secret dockersecret -replicas 2 -nodePort 3${port} -requestCpu 200 -requestMem 50 -limitCpu 300 -limitMem 100 -name ${JOB_NAME}-${type} -namespace hey-go-zero -image ${dockerServer}/${image} -o ${deployYaml} -port ${port}'
+ sh '/usr/bin/kubectl apply -f ${deployYaml}'
+ }
+ }
+
+ stage('Clean') {
+ steps{
+ sh 'docker rmi -f ${image}'
+ sh 'docker rmi -f ${dockerServer}/${image}'
+ cleanWs notFailBuild: true
+ }
+ }
+ }
+}
+```
+
+> [!TIP]
+> ${credentialsId}要替换为你的具体凭据值，即【添加凭据】模块中的一串字符串，${gitUrl}需要替换为你代码的git仓库地址，其他的${xxx}形式的变量无需修改，保持原样即可。
+> 
+
+### port.sh参考内容如下
+```
+case $1 in
+"user-api") echo 1000
+;;
+"user-rpc") echo 1001
+;;
+"course-api") echo 1002
+;;
+"course-rpc") echo 1003
+;;
+"selection-api") echo 1004
+esac
+```
+
+其中dockerlogin.sh内容
+
+```shell
+#!/bin/bash
+docker login --username=$docker-user --password=$docker-pass $docker-server
+```
+
+* $docker-user: docker登录用户名
+* $docker-pass: docker登录用户密码
+* $docker-server: docker私有地址
+
+
+## 查看pipeline
+
+
+
+## 查看k8s服务
+
+
+# 猜你想看
+* [goctl安装](goctl-install.md)
+* [k8s介绍](https://kubernetes.io/zh/)
+* [docker介绍](https://www.docker.com/)
+* [jenkins安装](https://www.jenkins.io/zh/doc/book/installing/)
+* [jenkins pipeline](https://www.jenkins.io/zh/doc/pipeline/tour/hello-world/)
+* [nginx文档介绍](http://nginx.org/en/docs/)
+* [etcd文档说明](https://etcd.io/docs/current/)
\ No newline at end of file
diff --git a/go-zero.dev/cn/service-design.md b/go-zero.dev/cn/service-design.md
new file mode 100644
index 00000000..d1805335
--- /dev/null
+++ b/go-zero.dev/cn/service-design.md
@@ -0,0 +1,88 @@
+# 目录拆分
+目录拆分是指配合go-zero的最佳实践的目录拆分，这和微服务拆分有着关联，在团队内部最佳实践中，
+我们按照业务横向拆分，将一个系统拆分成多个子系统，每个子系统应拥有独立的持久化存储，缓存系统。
+如一个商城系统需要有用户系统(user)，商品管理系统(product)，订单系统(order)，购物车系统(cart)，结算中心系统(pay)，售后系统(afterSale)等组成。
+
+## 系统结构分析
+在上文提到的商城系统中，每个系统在对外（http）提供服务的同时，也会提供数据给其他子系统进行数据访问的接口（rpc），因此每个子系统可以拆分成一个服务，而且对外提供了两种访问该系统的方式api和rpc，因此，
+以上系统按照目录结构来拆分有如下结构:
+
+```text
+.
+├── afterSale
+│ ├── api
+│ └── rpc
+├── cart
+│ ├── api
+│ └── rpc
+├── order
+│ ├── api
+│ └── rpc
+├── pay
+│ ├── api
+│ └── rpc
+├── product
+│ ├── api
+│ └── rpc
+└── user
+ ├── api
+ └── rpc
+```
+
+## rpc调用链建议
+在设计系统时，尽量做到服务之间调用链是单向的，而非循环调用，例如：order服务调用了user服务，而user服务反过来也会调用order的服务，
+当其中一个服务启动故障，就会相互影响，进入死循环，你order认为是user服务故障导致的，而user认为是order服务导致的，如果有大量服务存在相互调用链，
+则需要考虑服务拆分是否合理。
+
+## 常见服务类型的目录结构
+在上述服务中，仅列举了api/rpc服务，除此之外，一个服务下还可能有其他更多服务类型，如rmq（消息处理系统），cron（定时任务系统），script（脚本）等，
+因此一个服务下可能包含以下目录结构：
+```text
+user
+ ├── api // http访问服务，业务需求实现
+ ├── cronjob // 定时任务，定时数据更新业务
+ ├── rmq // 消息处理系统：mq和dq，处理一些高并发和延时消息业务
+ ├── rpc // rpc服务，给其他子系统提供基础数据访问
+ └── script // 脚本，处理一些临时运营需求，临时数据修复
+```
+
+## 完整工程目录结构示例
+```text
+mall // 工程名称
+├── common // 通用库
+│ ├── randx
+│ └── stringx
+├── go.mod
+├── go.sum
+└── service // 服务存放目录
+ ├── afterSale
+ │ ├── api
+ │ └── model
+ │ └── rpc
+ ├── cart
+ │ ├── api
+ │ └── model
+ │ └── rpc
+ ├── order
+ │ ├── api
+ │ └── model
+ │ └── rpc
+ ├── pay
+ │ ├── api
+ │ └── model
+ │ └── rpc
+ ├── product
+ │ ├── api
+ │ └── model
+ │ └── rpc
+ └── user
+ ├── api
+ ├── cronjob
+ ├── model
+ ├── rmq
+ ├── rpc
+ └── script
+```
+
+# 猜你想看
+* [api目录结构介绍](api-dir.md)
diff --git a/go-zero.dev/cn/service-monitor.md b/go-zero.dev/cn/service-monitor.md
new file mode 100644
index 00000000..45da4f1c
--- /dev/null
+++ b/go-zero.dev/cn/service-monitor.md
@@ -0,0 +1,100 @@
+# 服务监控
+在微服务治理中，服务监控也是非常重要的一个环节，监控一个服务是否正常工作，需要从多维度进行，如：
+* mysql指标
+* mongo指标
+* redis指标
+* 请求日志
+* 服务指标统计
+* 服务健康检测
+...
+
+监控的工作非常大，本节仅以其中的`服务指标监控`作为例子进行说明。
+
+## 基于prometheus的微服务指标监控
+
+服务上线后我们往往需要对服务进行监控，以便能及早发现问题并做针对性的优化，监控又可分为多种形式，比如日志监控，调用链监控，指标监控等等。而通过指标监控能清晰的观察出服务指标的变化趋势，了解服务的运行状态，对于保证服务稳定起着非常重要的作用
+prometheus是一个开源的系统监控和告警工具，支持强大的查询语言PromQL允许用户实时选择和汇聚时间序列数据，时间序列数据是服务端通过HTTP协议主动拉取获得，也可以通过中间网关来推送时间序列数据，可以通过静态配置文件或服务发现来获取监控目标
+
+##Prometheus 的架构
+
+Prometheus 的整体架构以及生态系统组件如下图所示：
+
+
+Prometheus Server直接从监控目标中或者间接通过推送网关来拉取监控指标，它在本地存储所有抓取到样本数据，并对此数据执行一系列规则，以汇总和记录现有数据的新时间序列或生成告警。可以通过 Grafana 或者其他工具来实现监控数据的可视化
+
+## go-zero基于prometheus的服务指标监控
+
+go-zero 框架中集成了基于prometheus的服务指标监控，下面我们通过go-zero官方的示例shorturl来演示是如何对服务指标进行收集监控的：
+* 第一步需要先安装Prometheus，安装步骤请参考官方文档
+* go-zero默认不开启prometheus监控，开启方式很简单，只需要在shorturl-api.yaml文件中增加配置如下，其中Host为Prometheus Server地址为必填配置，Port端口不填默认9091，Path为用来拉取指标的路径默认为/metrics
+ ```yaml
+ Prometheus:
+ Host: 127.0.0.1
+ Port: 9091
+ Path: /metrics
+ ```
+
+* 编辑prometheus的配置文件prometheus.yml，添加如下配置，并创建targets.json
+ ```yaml
+ - job_name: 'file_ds'
+ file_sd_configs:
+ - files:
+ - targets.json
+ ```
+* 编辑targets.json文件，其中targets为shorturl配置的目标地址，并添加了几个默认的标签
+ ```yaml
+ [
+ {
+ "targets": ["127.0.0.1:9091"],
+ "labels": {
+ "job": "shorturl-api",
+ "app": "shorturl-api",
+ "env": "test",
+ "instance": "127.0.0.1:8888"
+ }
+ }
+ ]
+ ```
+* 启动prometheus服务，默认侦听在9090端口
+ ```shell
+ $ prometheus --config.file=prometheus.yml
+ ```
+* 在浏览器输入`http://127.0.0.1:9090/`，然后点击`Status` -> `Targets`即可看到状态为Up的Job，并且Lables栏可以看到我们配置的默认的标签
+
+通过以上几个步骤我们完成了prometheus对shorturl服务的指标监控收集的配置工作，为了演示简单我们进行了手动的配置，在实际的生产环境中一般采用定时更新配置文件或者服务发现的方式来配置监控目标，篇幅有限这里不展开讲解，感兴趣的同学请自行查看相关文档
+
+## go-zero监控的指标类型
+
+go-zero目前在http的中间件和rpc的拦截器中添加了对请求指标的监控。
+
+主要从请求耗时和请求错误两个维度，请求耗时采用了Histogram指标类型定义了多个Buckets方便进行分位统计，请求错误采用了Counter类型，并在http metric中添加了path标签rpc metric中添加了method标签以便进行细分监控。
+接下来演示如何查看监控指标：
+首先在命令行多次执行如下命令
+```shell
+$ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn"
+```
+打开Prometheus切换到Graph界面，在输入框中输入{path="/shorten"}指令，即可查看监控指标，如下图
+
+
+我们通过PromQL语法查询过滤path为/shorten的指标，结果中显示了指标名以及指标数值，其中http_server_requests_code_total指标中code值为http的状态码，200表明请求成功，http_server_requests_duration_ms_bucket中对不同bucket结果分别进行了统计，还可以看到所有的指标中都添加了我们配置的默认指标
+Console界面主要展示了查询的指标结果，Graph界面为我们提供了简单的图形化的展示界面，在实际的生产环境中我们一般使用Grafana做图形化的展示
+
+## grafana可视化界面
+
+grafana是一款可视化工具，功能强大，支持多种数据来源Prometheus、Elasticsearch、Graphite等，安装比较简单请参考官方文档，grafana默认端口3000，安装好后再浏览器输入http://localhost:3000/，默认账号和密码都为admin
+下面演示如何基于以上指标进行可视化界面的绘制：
+点击左侧边栏`Configuration`->`Data Source`->`Add data source`进行数据源添加，其中HTTP的URL为数据源的地址
+
+
+点击左侧边栏添加dashboard，然后添加Variables方便针对不同的标签进行过滤筛选比如添加app变量用来过滤不同的服务
+
+
+进入dashboard点击右上角Add panel添加面板，以path维度统计接口的qps
+
+
+最终的效果如下所示，可以通过服务名称过滤不同的服务，面板展示了path为/shorten的qps变化趋势
+
+
+# 总结
+
+以上演示了go-zero中基于prometheus+grafana服务指标监控的简单流程，生产环境中可以根据实际的场景做不同维度的监控分析。现在go-zero的监控指标主要还是针对http和rpc，这对于服务的整体监控显然还是不足的，比如容器资源的监控，依赖的mysql、redis等资源的监控，以及自定义的指标监控等等，go-zero在这方面后续还会持续优化。希望这篇文章能够给您带来帮助
\ No newline at end of file
diff --git a/doc/sharedcalls.md b/go-zero.dev/cn/sharedcalls.md
similarity index 95%
rename from doc/sharedcalls.md
rename to go-zero.dev/cn/sharedcalls.md
index d640a28b..991e726e 100644
--- a/doc/sharedcalls.md
+++ b/go-zero.dev/cn/sharedcalls.md
@@ -2,13 +2,13 @@
go-zero微服务框架中提供了许多开箱即用的工具，好的工具不仅能提升服务的性能而且还能提升代码的鲁棒性避免出错，实现代码风格的统一方便他人阅读等等。
-本文主要讲述进程内共享调用神器[SharedCalls](https://github.com/tal-tech/go-zero/blob/master/core/syncx/sharedcalls.go)。
+本文主要讲述进程内共享调用神器[SharedCalls](https://github.com/zeromicro/go-zero/blob/master/core/syncx/sharedcalls.go)。
## 使用场景
并发场景下，可能会有多个线程（协程）同时请求同一份资源，如果每个请求都要走一遍资源的请求过程，除了比较低效之外，还会对资源服务造成并发的压力。举一个具体例子，比如缓存失效，多个请求同时到达某服务请求某资源，该资源在缓存中已经失效，此时这些请求会继续访问DB做查询，会引起数据库压力瞬间增大。而使用SharedCalls可以使得同时多个请求只需要发起一次拿结果的调用，其他请求"坐享其成"，这种设计有效减少了资源服务的并发压力，可以有效防止缓存击穿。
-高并发场景下，当某个热点key缓存失效后，多个请求会同时从数据库加载该资源，并保存到缓存，如果不做防范，可能会导致数据库被直接打死。针对这种场景，go-zero框架中已经提供了实现，具体可参看[sqlc](https://github.com/tal-tech/go-zero/blob/master/core/stores/sqlc/cachedsql.go)和[mongoc](https://github.com/tal-tech/go-zero/blob/master/core/stores/mongoc/cachedcollection.go)等实现代码。
+高并发场景下，当某个热点key缓存失效后，多个请求会同时从数据库加载该资源，并保存到缓存，如果不做防范，可能会导致数据库被直接打死。针对这种场景，go-zero框架中已经提供了实现，具体可参看[sqlc](https://github.com/zeromicro/go-zero/blob/master/core/stores/sqlc/cachedsql.go)和[mongoc](https://github.com/zeromicro/go-zero/blob/master/core/stores/mongoc/cachedcollection.go)等实现代码。
为了简化演示代码，我们通过多个线程同时去获取一个id来模拟缓存的场景。如下：
diff --git a/go-zero.dev/cn/shorturl.md b/go-zero.dev/cn/shorturl.md
new file mode 100644
index 00000000..72ec58eb
--- /dev/null
+++ b/go-zero.dev/cn/shorturl.md
@@ -0,0 +1,588 @@
+# 快速构建高并发微服务
+
+[English](../en/shorturl-en.md) | 简体中文
+
+## 0. 为什么说做好微服务很难
+
+要想做好微服务，我们需要理解和掌握的知识点非常多，从几个维度上来说：
+
+* 基本功能层面
+ 1. 并发控制 & 限流，避免服务被突发流量击垮
+ 2. 服务注册与服务发现，确保能够动态侦测增减的节点
+ 3. 负载均衡，需要根据节点承受能力分发流量
+ 4. 超时控制，避免对已超时请求做无用功
+ 5. 熔断设计，快速失败，保障故障节点的恢复能力
+
+* 高阶功能层面
+ 1. 请求认证，确保每个用户只能访问自己的数据
+ 2. 链路追踪，用于理解整个系统和快速定位特定请求的问题
+ 3. 日志，用于数据收集和问题定位
+ 4. 可观测性，没有度量就没有优化
+
+对于其中每一点，我们都需要用很长的篇幅来讲述其原理和实现，那么对我们后端开发者来说，要想把这些知识点都掌握并落实到业务系统里，难度是非常大的，不过我们可以依赖已经被大流量验证过的框架体系。[go-zero 微服务框架](https://github.com/zeromicro/go-zero)就是为此而生。
+
+另外，我们始终秉承 **工具大于约定和文档** 的理念。我们希望尽可能减少开发人员的心智负担，把精力都投入到产生业务价值的代码上，减少重复代码的编写，所以我们开发了 `goctl` 工具。
+
+下面我通过短链微服务来演示通过 [go-zero](https://github.com/zeromicro/go-zero) 快速的创建微服务的流程，走完一遍，你就会发现：原来编写微服务如此简单！
+
+## 1. 什么是短链服务
+
+短链服务就是将长的 URL 网址，通过程序计算等方式，转换为简短的网址字符串。
+
+写此短链服务是为了从整体上演示 go-zero 构建完整微服务的过程，算法和实现细节尽可能简化了，所以这不是一个高阶的短链服务。
+
+## 2. 短链微服务架构图
+
+
+
+* 这里只用了 `Transform RPC` 一个微服务，并不是说 API Gateway 只能调用一个微服务，只是为了最简演示 API Gateway 如何调用 RPC 微服务而已
+* 在真正项目里要尽可能每个微服务使用自己的数据库，数据边界要清晰
+
+## 3. goctl 各层代码生成一览
+
+所有绿色背景的功能模块是自动生成的，按需激活，红色模块是需要自己写的，也就是增加下依赖，编写业务特有逻辑，各层示意图分别如下：
+
+* API Gateway
+
+ 
+
+* RPC
+
+ 
+
+* model
+
+ 
+
+下面我们来一起完整走一遍快速构建微服务的流程，Let’s `Go`!🏃♂️
+
+## 4. 准备工作
+
+* 安装 etcd, mysql, redis
+
+* 安装 `protoc-gen-go`
+
+ ```shell
+ go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2
+ ```
+* 安装 `protoc`
+ ``` shell
+ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.14.0/protoc-3.14.0-linux-x86_64.zip
+ unzip protoc-3.14.0-linux-x86_64.zip
+ mv bin/protoc /usr/local/bin/
+ ```
+
+* 安装 goctl 工具
+
+ ```shell
+ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl
+ ```
+
+* 创建工作目录 `shorturl` 和 `shorturl/api`
+
+`mkdir -p shorturl/api`
+
+* 在 `shorturl` 目录下执行 `go mod init shorturl` 初始化 `go.mod`
+
+ ```Plain Text
+ module shorturl
+
+ go 1.15
+
+ require (
+ github.com/golang/mock v1.4.3
+ github.com/golang/protobuf v1.4.2
+ github.com/tal-tech/go-zero v1.1.4
+ golang.org/x/net v0.0.0-20200707034311-ab3426394381
+ google.golang.org/grpc v1.29.1
+ )
+ ```
+
+ **注意：这里可能存在 grpc 版本依赖的问题，可以用以上配置**
+
+## 5. 编写 API Gateway 代码
+
+* 在 `shorturl/api` 目录下通过 goctl 生成 `api/shorturl.api`：
+
+ ```shell
+ goctl api -o shorturl.api
+ ```
+
+* 编辑 `api/shorturl.api`，为了简洁，去除了文件开头的 `info`，代码如下：
+
+ ```go
+ type (
+ expandReq {
+ shorten string `form:"shorten"`
+ }
+
+ expandResp {
+ url string `json:"url"`
+ }
+ )
+
+ type (
+ shortenReq {
+ url string `form:"url"`
+ }
+
+ shortenResp {
+ shorten string `json:"shorten"`
+ }
+ )
+
+ service shorturl-api {
+ @server(
+ handler: ShortenHandler
+ )
+ get /shorten(shortenReq) returns(shortenResp)
+
+ @server(
+ handler: ExpandHandler
+ )
+ get /expand(expandReq) returns(expandResp)
+ }
+ ```
+
+ type 用法和 go 一致，service 用来定义 get/post/head/delete 等 api 请求，解释如下：
+
+ * `service shorturl-api {` 这一行定义了 service 名字
+ * `@server` 部分用来定义 server 端用到的属性
+ * `handler` 定义了服务端 handler 名字
+ * `get /shorten(shortenReq) returns(shortenResp)` 定义了 get 方法的路由、请求参数、返回参数等
+
+* 使用 goctl 生成 API Gateway 代码
+
+ ```shell
+ goctl api go -api shorturl.api -dir .
+ ```
+
+ 生成的文件结构如下：
+
+ ```Plain Text
+ .
+ ├── api
+ │ ├── etc
+ │ │ └── shorturl-api.yaml // 配置文件
+ │ ├── internal
+ │ │ ├── config
+ │ │ │ └── config.go // 定义配置
+ │ │ ├── handler
+ │ │ │ ├── expandhandler.go // 实现 expandHandler
+ │ │ │ ├── routes.go // 定义路由处理
+ │ │ │ └── shortenhandler.go // 实现 shortenHandler
+ │ │ ├── logic
+ │ │ │ ├── expandlogic.go // 实现 ExpandLogic
+ │ │ │ └── shortenlogic.go // 实现 ShortenLogic
+ │ │ ├── svc
+ │ │ │ └── servicecontext.go // 定义 ServiceContext
+ │ │ └── types
+ │ │ └── types.go // 定义请求、返回结构体
+ │ ├── shorturl.api
+ │ └── shorturl.go // main 入口定义
+ ├── go.mod
+ └── go.sum
+ ```
+
+* 启动 API Gateway 服务，默认侦听在 8888 端口
+
+ ```shell
+ go run shorturl.go -f etc/shorturl-api.yaml
+ ```
+
+* 测试 API Gateway 服务
+
+ ```shell
+ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn"
+ ```
+
+ 返回如下：
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Thu, 27 Aug 2020 14:31:39 GMT
+ Content-Length: 15
+
+ {"shorten":""}
+ ```
+
+ 可以看到我们 API Gateway 其实啥也没干，就返回了个空值，接下来我们会在 rpc 服务里实现业务逻辑
+
+* 可以修改 `internal/svc/servicecontext.go` 来传递服务依赖（如果需要）
+
+* 实现逻辑可以修改 `internal/logic` 下的对应文件
+
+* 可以通过 `goctl` 生成各种客户端语言的 api 调用代码
+
+* 到这里，你已经可以通过 goctl 生成客户端代码给客户端同学并行开发了，支持多种语言，详见文档
+
+## 6. 编写 transform rpc 服务
+
+- 在 `shorturl` 目录下创建 `rpc` 目录
+
+* 在 `rpc/transform` 目录下编写 `transform.proto` 文件
+
+ 可以通过命令生成 proto 文件模板
+
+ ```shell
+ goctl rpc template -o transform.proto
+ ```
+
+ 修改后文件内容如下：
+
+ ```protobuf
+ syntax = "proto3";
+
+ package transform;
+
+ message expandReq {
+ string shorten = 1;
+ }
+
+ message expandResp {
+ string url = 1;
+ }
+
+ message shortenReq {
+ string url = 1;
+ }
+
+ message shortenResp {
+ string shorten = 1;
+ }
+
+ service transformer {
+ rpc expand(expandReq) returns(expandResp);
+ rpc shorten(shortenReq) returns(shortenResp);
+ }
+ ```
+
+* 用 `goctl` 生成 rpc 代码，在 `rpc/transform` 目录下执行命令
+
+ ```shell
+ goctl rpc proto -src transform.proto -dir .
+ ```
+
+ **注意：不能在 GOPATH 目录下执行以上命令**
+
+ 文件结构如下：
+
+ ```Plain Text
+ rpc/transform
+ ├── etc
+ │ └── transform.yaml // 配置文件
+ ├── internal
+ │ ├── config
+ │ │ └── config.go // 配置定义
+ │ ├── logic
+ │ │ ├── expandlogic.go // expand 业务逻辑在这里实现
+ │ │ └── shortenlogic.go // shorten 业务逻辑在这里实现
+ │ ├── server
+ │ │ └── transformerserver.go // 调用入口, 不需要修改
+ │ └── svc
+ │ └── servicecontext.go // 定义 ServiceContext，传递依赖
+ ├── pb
+ │ └── transform.pb.go
+ ├── transform.go // rpc 服务 main 函数
+ ├── transform.proto
+ └── transformer
+ ├── transformer.go // 提供了外部调用方法，无需修改
+ ├── transformer_mock.go // mock 方法，测试用
+ └── types.go // request/response 结构体定义
+ ```
+
+ 直接可以运行，如下：
+
+ ```shell
+ $ go run transform.go -f etc/transform.yaml
+ Starting rpc server at 127.0.0.1:8080...
+ ```
+ 查看服务是否注册
+ ```
+ $ETCDCTL_API=3 etcdctl get transform.rpc --prefix
+ transform.rpc/7587851893787585061
+ 127.0.0.1:8080
+ ```
+ `etc/transform.yaml` 文件里可以修改侦听端口等配置
+
+## 7. 修改 API Gateway 代码调用 transform rpc 服务
+
+* 修改配置文件 `shorturl-api.yaml`，增加如下内容
+
+ ```yaml
+ Transform:
+ Etcd:
+ Hosts:
+ - localhost:2379
+ Key: transform.rpc
+ ```
+
+ 通过 etcd 自动去发现可用的 transform 服务
+
+* 修改 `internal/config/config.go` 如下，增加 transform 服务依赖
+
+ ```go
+ type Config struct {
+ rest.RestConf
+ Transform zrpc.RpcClientConf // 手动代码
+ }
+ ```
+
+* 修改 `internal/svc/servicecontext.go`，如下：
+
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ Transformer transformer.Transformer // 手动代码
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ Transformer: transformer.NewTransformer(zrpc.MustNewClient(c.Transform)), // 手动代码
+ }
+ }
+ ```
+
+ 通过 ServiceContext 在不同业务逻辑之间传递依赖
+
+* 修改 `internal/logic/expandlogic.go` 里的 `Expand` 方法，如下：
+
+ ```go
+ func (l *ExpandLogic) Expand(req types.ExpandReq) (types.ExpandResp, error) {
+ // 手动代码开始
+ resp, err := l.svcCtx.Transformer.Expand(l.ctx, &transformer.ExpandReq{
+ Shorten: req.Shorten,
+ })
+ if err != nil {
+ return types.ExpandResp{}, err
+ }
+
+ return types.ExpandResp{
+ Url: resp.Url,
+ }, nil
+ // 手动代码结束
+ }
+ ```
+
+通过调用 `transformer` 的 `Expand` 方法实现短链恢复到 url
+
+* 修改 `internal/logic/shortenlogic.go`，如下：
+
+ ```go
+ func (l *ShortenLogic) Shorten(req types.ShortenReq) (types.ShortenResp, error) {
+ // 手动代码开始
+ resp, err := l.svcCtx.Transformer.Shorten(l.ctx, &transformer.ShortenReq{
+ Url: req.Url,
+ })
+ if err != nil {
+ return types.ShortenResp{}, err
+ }
+
+ return types.ShortenResp{
+ Shorten: resp.Shorten,
+ }, nil
+ // 手动代码结束
+ }
+ ```
+有的版本生成返回值可能是指针类型，需要自己调整下
+
+通过调用 `transformer` 的 `Shorten` 方法实现 url 到短链的变换
+
+至此，API Gateway 修改完成，虽然贴的代码多，但是其中修改的是很少的一部分，为了方便理解上下文，我贴了完整代码，接下来处理 CRUD+cache
+
+## 8. 定义数据库表结构，并生成 CRUD+cache 代码
+
+* shorturl 下创建 `rpc/transform/model` 目录：`mkdir -p rpc/transform/model`
+
+* 在 `rpc/transform/model` 目录下编写创建 shorturl 表的 sql 文件 `shorturl.sql`，如下：
+
+ ```sql
+ CREATE TABLE `shorturl`
+ (
+ `shorten` varchar(255) NOT NULL COMMENT 'shorten key',
+ `url` varchar(255) NOT NULL COMMENT 'original url',
+ PRIMARY KEY(`shorten`)
+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+ ```
+
+* 创建 DB 和 table
+
+ ```sql
+ create database gozero;
+ ```
+
+ ```sql
+ source shorturl.sql;
+ ```
+
+* 在 `rpc/transform/model` 目录下执行如下命令生成 CRUD+cache 代码，`-c` 表示使用 `redis cache`
+
+ ```shell
+ goctl model mysql ddl -c -src shorturl.sql -dir .
+ ```
+
+ 也可以用 `datasource` 命令代替 `ddl` 来指定数据库链接直接从 schema 生成
+
+ 生成后的文件结构如下：
+
+ ```Plain Text
+ rpc/transform/model
+ ├── shorturl.sql
+ ├── shorturlmodel.go // CRUD+cache 代码
+ └── vars.go // 定义常量和变量
+ ```
+
+## 9. 修改 shorten/expand rpc 代码调用 crud+cache 代码
+
+* 修改 `rpc/transform/etc/transform.yaml`，增加如下内容：
+
+ ```yaml
+ DataSource: root:password@tcp(localhost:3306)/gozero
+ Table: shorturl
+ Cache:
+ - Host: localhost:6379
+ ```
+
+ 可以使用多个 redis 作为 cache，支持 redis 单点或者 redis 集群
+
+* 修改 `rpc/transform/internal/config/config.go`，如下：
+
+ ```go
+ type Config struct {
+ zrpc.RpcServerConf
+ DataSource string // 手动代码
+ Table string // 手动代码
+ Cache cache.CacheConf // 手动代码
+ }
+ ```
+
+ 增加了 mysql 和 redis cache 配置
+
+* 修改 `rpc/transform/internal/svc/servicecontext.go`，如下：
+
+ ```go
+ type ServiceContext struct {
+ c config.Config
+ Model model.ShorturlModel // 手动代码
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ c: c,
+ Model: model.NewShorturlModel(sqlx.NewMysql(c.DataSource), c.Cache), // 手动代码
+ }
+ }
+ ```
+
+* 修改 `rpc/transform/internal/logic/expandlogic.go`，如下：
+
+ ```go
+ func (l *ExpandLogic) Expand(in *transform.ExpandReq) (*transform.ExpandResp, error) {
+ // 手动代码开始
+ res, err := l.svcCtx.Model.FindOne(in.Shorten)
+ if err != nil {
+ return nil, err
+ }
+
+ return &transform.ExpandResp{
+ Url: res.Url,
+ }, nil
+ // 手动代码结束
+ }
+ ```
+
+* 修改 `rpc/transform/internal/logic/shortenlogic.go`，如下：
+
+ ```go
+ func (l *ShortenLogic) Shorten(in *transform.ShortenReq) (*transform.ShortenResp, error) {
+ // 手动代码开始，生成短链接
+ key := hash.Md5Hex([]byte(in.Url))[:6]
+ _, err := l.svcCtx.Model.Insert(model.Shorturl{
+ Shorten: key,
+ Url: in.Url,
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ return &transform.ShortenResp{
+ Shorten: key,
+ }, nil
+ // 手动代码结束
+ }
+ ```
+
+ 至此代码修改完成，凡是手动修改的代码我加了标注
+
+ **注意：**
+ 1. undefined cache，你需要 `import "github.com/tal-tech/go-zero/core/stores/cache"`
+ 2. undefined model, sqlx, hash 等，你需要在文件中
+
+ ```golang
+ import "shorturl/rpc/transform/model"
+
+ import "github.com/tal-tech/go-zero/core/stores/sqlx"
+ ```
+
+## 10. 完整调用演示
+
+* shorten api 调用
+
+ ```shell
+ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn"
+ ```
+
+ 返回如下：
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sat, 29 Aug 2020 10:49:49 GMT
+ Content-Length: 21
+
+ {"shorten":"f35b2a"}
+ ```
+
+* expand api 调用
+
+ ```shell
+ curl -i "http://localhost:8888/expand?shorten=f35b2a"
+ ```
+
+ 返回如下：
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sat, 29 Aug 2020 10:51:53 GMT
+ Content-Length: 34
+
+ {"url":"http://www.xiaoheiban.cn"}
+ ```
+
+## 11. Benchmark
+
+因为写入依赖于 mysql 的写入速度，就相当于压 mysql 了，所以压测只测试了 expand 接口，相当于从 mysql 里读取并利用缓存，shorten.lua 里随机从 db 里获取了 100 个热 key 来生成压测请求
+
+
+
+可以看出在我的 MacBook Pro 上能达到 3 万 + 的 qps。
+
+## 12. 完整代码
+
+[https://github.com/zeromicro/zero-examples/tree/main/shorturl](https://github.com/zeromicro/zero-examples/tree/main/shorturl)
+
+## 12. 总结
+
+我们一直强调 **工具大于约定和文档**。
+
+go-zero 不只是一个框架，更是一个建立在框架 + 工具基础上的，简化和规范了整个微服务构建的技术体系。
+
+我们在保持简单的同时也尽可能把微服务治理的复杂度封装到了框架内部，极大的降低了开发人员的心智负担，使得业务开发得以快速推进。
+
+通过 go-zero+goctl 生成的代码，包含了微服务治理的各种组件，包括：并发控制、自适应熔断、自适应降载、自动缓存控制等，可以轻松部署以承载巨大访问量。
+
+有任何好的提升工程效率的想法，随时欢迎交流！👏
+
diff --git a/go-zero.dev/cn/source.md b/go-zero.dev/cn/source.md
new file mode 100644
index 00000000..881e94d4
--- /dev/null
+++ b/go-zero.dev/cn/source.md
@@ -0,0 +1,2 @@
+# 相关源码
+* [demo源码](https://github.com/zeromicro/go-zero-demo)
\ No newline at end of file
diff --git a/go-zero.dev/cn/sql-cache.md b/go-zero.dev/cn/sql-cache.md
new file mode 100644
index 00000000..508e8b6e
--- /dev/null
+++ b/go-zero.dev/cn/sql-cache.md
@@ -0,0 +1,23 @@
+# DB缓存机制
+
+## QueryRowIndex
+
+* 没有查询条件到Primary映射的缓存
+ * 通过查询条件到DB去查询行记录，然后
+ * **把Primary到行记录的缓存写到redis里**
+ * **把查询条件到Primary的映射保存到redis里**，*框架的Take方法自动做了*
+ * 可能的过期顺序
+ * 查询条件到Primary的映射缓存未过期
+ * Primary到行记录的缓存未过期
+ * 直接返回缓存行记录
+ * Primary到行记录的缓存已过期
+ * 通过Primary到DB获取行记录，并写入缓存
+ * 此时存在的问题是，查询条件到Primary的缓存可能已经快要过期了，短时间内的查询又会触发一次数据库查询
+ * 要避免这个问题，可以让**上面粗体部分**第一个过期时间略长于第二个，比如5秒
+ * 查询条件到Primary的映射缓存已过期，不管Primary到行记录的缓存是否过期
+ * 查询条件到Primary的映射会被重新获取，获取过程中会自动写入新的Primary到行记录的缓存，这样两种缓存的过期时间都是刚刚设置
+* 有查询条件到Primary映射的缓存
+ * 没有Primary到行记录的缓存
+ * 通过Primary到DB查询行记录，并写入缓存
+ * 有Primary到行记录的缓存
+ * 直接返回缓存结果
diff --git a/go-zero.dev/cn/stream.md b/go-zero.dev/cn/stream.md
new file mode 100644
index 00000000..33ce302b
--- /dev/null
+++ b/go-zero.dev/cn/stream.md
@@ -0,0 +1,366 @@
+# 流数据处理利器
+
+流处理 (Stream processing) 是一种计算机编程范式，其允许给定一个数据序列 (流处理数据源)，一系列数据操作 (函数) 被应用到流中的每个元素。同时流处理工具可以显著提高程序员的开发效率，允许他们编写有效、干净和简洁的代码。
+
+流数据处理在我们的日常工作中非常常见，举个例子，我们在业务开发中往往会记录许多业务日志，这些日志一般是先发送到 Kafka，然后再由 Job 消费 Kafaka 写到 elasticsearch，在进行日志流处理的过程中，往往还会对日志做一些处理，比如过滤无效的日志，做一些计算以及重新组合日志等等，示意图如下:
+
+### 流处理工具fx
+[go-zero](https://github.com/zeromicro/go-zero) 是一个功能完备的微服务框架，框架中内置了很多非常实用的工具，其中就包含流数据处理工具[fx](https://github.com/zeromicro/go-zero/tree/master/core/fx) ，下面我们通过一个简单的例子来认识下该工具：
+```go
+package main
+
+import (
+ "fmt"
+ "os"
+ "os/signal"
+ "syscall"
+ "time"
+
+ "github.com/tal-tech/go-zero/core/fx"
+)
+
+func main() {
+ ch := make(chan int)
+
+ go inputStream(ch)
+ go outputStream(ch)
+
+ c := make(chan os.Signal, 1)
+ signal.Notify(c, syscall.SIGTERM, syscall.SIGINT)
+ <-c
+}
+
+func inputStream(ch chan int) {
+ count := 0
+ for {
+ ch <- count
+ time.Sleep(time.Millisecond * 500)
+ count++
+ }
+}
+
+func outputStream(ch chan int) {
+ fx.From(func(source chan<- interface{}) {
+ for c := range ch {
+ source <- c
+ }
+ }).Walk(func(item interface{}, pipe chan<- interface{}) {
+ count := item.(int)
+ pipe <- count
+ }).Filter(func(item interface{}) bool {
+ itemInt := item.(int)
+ if itemInt%2 == 0 {
+ return true
+ }
+ return false
+ }).ForEach(func(item interface{}) {
+ fmt.Println(item)
+ })
+}
+```
+
+
+inputStream函数模拟了流数据的产生，outputStream函数模拟了流数据的处理过程，其中From函数为流的输入，Walk函数并发的作用在每一个item上，Filter函数对item进行过滤为true保留为false不保留，ForEach函数遍历输出每一个item元素。
+
+
+### 流数据处理中间操作
+
+
+一个流的数据处理可能存在许多的中间操作，每个中间操作都可以作用在流上。就像流水线上的工人一样，每个工人操作完零件后都会返回处理完成的新零件，同理流处理中间操作完成后也会返回一个新的流。
+
+fx的流处理中间操作:
+
+| 操作函数 | 功能 | 输入 |
+| --- | --- | --- |
+| Distinct | 去除重复的item | KeyFunc，返回需要去重的key |
+| Filter | 过滤不满足条件的item | FilterFunc，Option控制并发量 |
+| Group | 对item进行分组 | KeyFunc，以key进行分组 |
+| Head | 取出前n个item，返回新stream | int64保留数量 |
+| Map | 对象转换 | MapFunc，Option控制并发量 |
+| Merge | 合并item到slice并生成新stream | |
+| Reverse | 反转item | |
+| Sort | 对item进行排序 | LessFunc实现排序算法 |
+| Tail | 与Head功能类似，取出后n个item组成新stream | int64保留数量 |
+| Walk | 作用在每个item上 | WalkFunc，Option控制并发量 |
+
+
+
+下图展示了每个步骤和每个步骤的结果:
+
+
+
+
+
+### 用法与原理分析
+
+
+#### From
+
+
+通过From函数构建流并返回Stream，流数据通过channel进行存储：
+
+
+```go
+// 例子
+s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 0}
+fx.From(func(source chan<- interface{}) {
+ for _, v := range s {
+ source <- v
+ }
+})
+
+// 源码
+func From(generate GenerateFunc) Stream {
+ source := make(chan interface{})
+
+ threading.GoSafe(func() {
+ defer close(source)
+ // 构造流数据写入channel
+ generate(source)
+ })
+
+ return Range(source)
+}
+```
+
+
+#### Filter
+
+
+Filter函数提供过滤item的功能，FilterFunc定义过滤逻辑true保留item，false则不保留:
+
+
+```go
+// 例子 保留偶数
+s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 0}
+fx.From(func(source chan<- interface{}) {
+ for _, v := range s {
+ source <- v
+ }
+}).Filter(func(item interface{}) bool {
+ if item.(int)%2 == 0 {
+ return true
+ }
+ return false
+})
+
+// 源码
+func (p Stream) Filter(fn FilterFunc, opts ...Option) Stream {
+ return p.Walk(func(item interface{}, pipe chan<- interface{}) {
+ // 执行过滤函数true保留，false丢弃
+ if fn(item) {
+ pipe <- item
+ }
+ }, opts...)
+}
+```
+
+
+#### Group
+
+
+Group对流数据进行分组，需定义分组的key，数据分组后以slice存入channel:
+
+
+```go
+// 例子 按照首字符"g"或者"p"分组，没有则分到另一组
+ ss := []string{"golang", "google", "php", "python", "java", "c++"}
+ fx.From(func(source chan<- interface{}) {
+ for _, s := range ss {
+ source <- s
+ }
+ }).Group(func(item interface{}) interface{} {
+ if strings.HasPrefix(item.(string), "g") {
+ return "g"
+ } else if strings.HasPrefix(item.(string), "p") {
+ return "p"
+ }
+ return ""
+ }).ForEach(func(item interface{}) {
+ fmt.Println(item)
+ })
+}
+
+// 源码
+func (p Stream) Group(fn KeyFunc) Stream {
+ // 定义分组存储map
+ groups := make(map[interface{}][]interface{})
+ for item := range p.source {
+ // 用户自定义分组key
+ key := fn(item)
+ // key相同分到一组
+ groups[key] = append(groups[key], item)
+ }
+
+ source := make(chan interface{})
+ go func() {
+ for _, group := range groups {
+ // 相同key的一组数据写入到channel
+ source <- group
+ }
+ close(source)
+ }()
+
+ return Range(source)
+}
+```
+
+
+#### Reverse
+
+
+reverse可以对流中元素进行反转处理:
+
+
+
+
+
+```go
+// 例子
+fx.Just(1, 2, 3, 4, 5).Reverse().ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+
+// 源码
+func (p Stream) Reverse() Stream {
+ var items []interface{}
+ // 获取流中数据
+ for item := range p.source {
+ items = append(items, item)
+ }
+ // 反转算法
+ for i := len(items)/2 - 1; i >= 0; i-- {
+ opp := len(items) - 1 - i
+ items[i], items[opp] = items[opp], items[i]
+ }
+
+ // 写入流
+ return Just(items...)
+}
+```
+
+
+#### Distinct
+
+
+distinct对流中元素进行去重，去重在业务开发中比较常用，经常需要对用户id等做去重操作:
+
+
+```go
+// 例子
+fx.Just(1, 2, 2, 2, 3, 3, 4, 5, 6).Distinct(func(item interface{}) interface{} {
+ return item
+}).ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+// 结果为 1，2，3，4，5，6
+
+// 源码
+func (p Stream) Distinct(fn KeyFunc) Stream {
+ source := make(chan interface{})
+
+ threading.GoSafe(func() {
+ defer close(source)
+ // 通过key进行去重，相同key只保留一个
+ keys := make(map[interface{}]lang.PlaceholderType)
+ for item := range p.source {
+ key := fn(item)
+ // key存在则不保留
+ if _, ok := keys[key]; !ok {
+ source <- item
+ keys[key] = lang.Placeholder
+ }
+ }
+ })
+
+ return Range(source)
+}
+```
+
+
+#### Walk
+
+
+Walk函数并发的作用在流中每一个item上，可以通过WithWorkers设置并发数，默认并发数为16，最小并发数为1，如设置unlimitedWorkers为true则并发数无限制，但并发写入流中的数据由defaultWorkers限制，WalkFunc中用户可以自定义后续写入流中的元素，可以不写入也可以写入多个元素:
+
+
+```go
+// 例子
+fx.Just("aaa", "bbb", "ccc").Walk(func(item interface{}, pipe chan<- interface{}) {
+ newItem := strings.ToUpper(item.(string))
+ pipe <- newItem
+}).ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+
+// 源码
+func (p Stream) walkLimited(fn WalkFunc, option *rxOptions) Stream {
+ pipe := make(chan interface{}, option.workers)
+
+ go func() {
+ var wg sync.WaitGroup
+ pool := make(chan lang.PlaceholderType, option.workers)
+
+ for {
+ // 控制并发数量
+ pool <- lang.Placeholder
+ item, ok := <-p.source
+ if !ok {
+ <-pool
+ break
+ }
+
+ wg.Add(1)
+ go func() {
+ defer func() {
+ wg.Done()
+ <-pool
+ }()
+ // 作用在每个元素上
+ fn(item, pipe)
+ }()
+ }
+
+ // 等待处理完成
+ wg.Wait()
+ close(pipe)
+ }()
+
+ return Range(pipe)
+}
+```
+
+
+### 并发处理
+
+
+fx工具除了进行流数据处理以外还提供了函数并发功能，在微服务中实现某个功能往往需要依赖多个服务，并发的处理依赖可以有效的降低依赖耗时，提升服务的性能。
+
+
+
+
+
+```go
+fx.Parallel(func() {
+ userRPC() // 依赖1
+}, func() {
+ accountRPC() // 依赖2
+}, func() {
+ orderRPC() // 依赖3
+})
+```
+
+
+注意fx.Parallel进行依赖并行处理的时候不会有error返回，如需有error返回或者有一个依赖报错需要立马结束依赖请求请使用[MapReduce](https://gocn.vip/topics/10941) 工具进行处理。
+
+
+### 总结
+
+
+本篇文章介绍了流处理的基本概念和go-zero中的流处理工具fx，在实际的生产中流处理场景应用也非常多，希望本篇文章能给大家带来一定的启发，更好的应对工作中的流处理场景。
+
+
+
+
+
+
diff --git a/go-zero.dev/cn/summary.md b/go-zero.dev/cn/summary.md
new file mode 100644
index 00000000..b9cd106f
--- /dev/null
+++ b/go-zero.dev/cn/summary.md
@@ -0,0 +1,79 @@
+# Summary
+
+* [简介](README.md)
+* [阅读须知](tips.md)
+* [关于我们](about-us.md)
+* [加入我们](join-us.md)
+* [概念介绍](concept-introduction.md)
+* [快速开发](quick-start.md)
+ * [单体服务](monolithic-service.md)
+ * [微服务](micro-service.md)
+* [框架设计](framework-design.md)
+ * [go-zero设计理念](go-zero-design.md)
+ * [go-zero特点](go-zero-features.md)
+ * [api语法介绍](api-grammar.md)
+ * [api目录结构](api-dir.md)
+ * [rpc目录结构](rpc-dir.md)
+* [项目开发](project-dev.md)
+ * [准备工作](prepare.md)
+ * [golang安装](golang-install.md)
+ * [go module配置](gomod-config.md)
+ * [goctl安装](goctl-install.md)
+ * [protoc&protoc-gen-go安装](protoc-install.md)
+ * [其他](prepare-other.md)
+ * [开发规范](dev-specification.md)
+ * [命名规范](naming-spec.md)
+ * [路由规范](route-naming-spec.md)
+ * [编码规范](coding-spec.md)
+ * [开发流程](dev-flow.md)
+ * [配置介绍](config-introduction.md)
+ * [api配置](api-config.md)
+ * [rpc配置](rpc-config.md)
+ * [业务开发](business-dev.md)
+ * [目录拆分](service-design.md)
+ * [model生成](model-gen.md)
+ * [api文件编写](api-coding.md)
+ * [业务编码](business-coding.md)
+ * [jwt鉴权](jwt.md)
+ * [中间件使用](middleware.md)
+ * [rpc服务编写与调用](rpc-call.md)
+ * [错误处理](error-handle.md)
+ * [CI/CD](ci-cd.md)
+ * [服务部署](service-deployment.md)
+ * [日志收集](log-collection.md)
+ * [链路追踪](trace.md)
+ * [服务监控](service-monitor.md)
+* [Goctl](goctl.md)
+ * [命令大全](goctl-commands.md)
+ * [api命令](goctl-api.md)
+ * [rpc命令](goctl-rpc.md)
+ * [model命令](goctl-model.md)
+ * [plugin命令](goctl-plugin.md)
+ * [其他命令](goctl-other.md)
+* [模板管理](template-manage.md)
+ * [模板操作](template-cmd.md)
+ * [自定义模板](template.md)
+* [扩展阅读](extended-reading.md)
+ * [logx](logx.md)
+ * [bloom](bloom.md)
+ * [executors](executors.md)
+ * [fx](fx.md)
+ * [mysql](mysql.md)
+ * [redis-lock](redis-lock.md)
+ * [periodlimit](periodlimit.md)
+ * [tokenlimit](tokenlimit.md)
+ * [TimingWheel](timing-wheel.md)
+* [工具中心](tool-center.md)
+ * [intellij插件](intellij.md)
+ * [vscode插件](vscode.md)
+* [插件中心](plugin-center.md)
+* [学习资源](learning-resource.md)
+ * [公众号](wechat.md)
+ * [Go夜读](goreading.md)
+ * [Go开源说](gotalk.md)
+* [贡献人员](contributor.md)
+* [文档贡献](doc-contibute.md)
+* [常见错误处理](error.md)
+* [FAQ](faq.md)
+* [相关源码](source.md)
+
diff --git a/go-zero.dev/cn/template-cmd.md b/go-zero.dev/cn/template-cmd.md
new file mode 100644
index 00000000..7e56e4bb
--- /dev/null
+++ b/go-zero.dev/cn/template-cmd.md
@@ -0,0 +1,113 @@
+# 模板操作
+
+模板（Template）是数据驱动生成的基础，所有的代码（rest api、rpc、model、docker、kube）生成都会依赖模板，
+默认情况下，模板生成器会选择内存中的模板进行生成，而对于有模板修改需求的开发者来讲，则需要将模板进行落盘，
+从而进行模板修改，在下次代码生成时会加载指定路径下的模板进行生成。
+
+## 使用帮助
+```text
+NAME:
+ goctl template - template operation
+
+USAGE:
+ goctl template command [command options] [arguments...]
+
+COMMANDS:
+ init initialize the all templates(force update)
+ clean clean the all cache templates
+ update update template of the target category to the latest
+ revert revert the target template to the latest
+
+OPTIONS:
+ --help, -h show help
+```
+
+## 模板初始化
+```text
+NAME:
+ goctl template init - initialize the all templates(force update)
+
+USAGE:
+ goctl template init [command options] [arguments...]
+
+OPTIONS:
+ --home value the goctl home path of the template
+```
+
+## 清除模板
+```text
+NAME:
+ goctl template clean - clean the all cache templates
+
+USAGE:
+ goctl template clean [command options] [arguments...]
+
+OPTIONS:
+ --home value the goctl home path of the template
+```
+
+## 回滚指定分类模板
+```text
+NAME:
+ goctl template update - update template of the target category to the latest
+
+USAGE:
+ goctl template update [command options] [arguments...]
+
+OPTIONS:
+ --category value, -c value the category of template, enum [api,rpc,model,docker,kube]
+ --home value the goctl home path of the template
+```
+
+## 回滚模板
+```text
+NAME:
+ goctl template revert - revert the target template to the latest
+
+USAGE:
+ goctl template revert [command options] [arguments...]
+
+OPTIONS:
+ --category value, -c value the category of template, enum [api,rpc,model,docker,kube]
+ --name value, -n value the target file name of template
+ --home value the goctl home path of the template
+```
+
+> [!TIP]
+>
+> `--home` 指定模板存储路径
+
+## 模板加载
+
+在代码生成时可以通过`--home`来指定模板所在文件夹，目前已支持指定模板目录的命令有：
+
+- `goctl api go` 详情可以通过`goctl api go --help`查看帮助
+- `goctl docker` 详情可以通过`goctl docker --help`查看帮助
+- `goctl kube` 详情可以通过`goctl kube --help`查看帮助
+- `goctl rpc new` 详情可以通过`goctl rpc new --help`查看帮助
+- `goctl rpc proto` 详情可以通过`goctl rpc proto --help`查看帮助
+- `goctl model mysql ddl` 详情可以通过`goctl model mysql ddl --help`查看帮助
+- `goctl model mysql datasource` 详情可以通过`goctl model mysql datasource --help`查看帮助
+- `goctl model postgresql datasource` 详情可以通过`goctl model mysql datasource --help`查看帮助
+- `goctl model mongo` 详情可以通过`goctl model mongo --help`查看帮助
+
+默认情况（在不指定`--home`）会从`$HOME/.goctl`目录下读取。
+
+## 使用示例
+* 初始化模板到指定`$HOME/template`目录下
+```text
+$ goctl template init --home $HOME/template
+```
+
+```text
+Templates are generated in /Users/anqiansong/template, edit on your risk!
+```
+
+* 使用`$HOME/template`模板进行greet rpc生成
+```text
+$ goctl rpc new greet --home $HOME/template
+```
+
+```text
+Done
+```
\ No newline at end of file
diff --git a/go-zero.dev/cn/template-manage.md b/go-zero.dev/cn/template-manage.md
new file mode 100644
index 00000000..3f8e6dfd
--- /dev/null
+++ b/go-zero.dev/cn/template-manage.md
@@ -0,0 +1,4 @@
+# 模板管理
+
+- [模板操作](template-cmd.md)
+- [自定义模板](template-manage.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/template.md b/go-zero.dev/cn/template.md
new file mode 100644
index 00000000..51509d84
--- /dev/null
+++ b/go-zero.dev/cn/template.md
@@ -0,0 +1,158 @@
+# 模板修改
+
+## 场景
+实现统一格式的body响应，格式如下：
+```json
+{
+ "code": 0,
+ "msg": "OK",
+ "data": {} // ①
+}
+```
+
+① 实际响应数据
+
+> [!TIP]
+> `go-zero`生成的代码没有对其进行处理
+## 准备工作
+我们提前在`module`为`greet`的工程下的`response`包中写一个`Response`方法，目录树类似如下：
+```text
+greet
+├── reponse
+│ └── response.go
+└── xxx...
+```
+
+代码如下
+```go
+package reponse
+
+import (
+ "net/http"
+
+ "github.com/tal-tech/go-zero/rest/httpx"
+)
+
+type Body struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ Data interface{} `json:"data,omitempty"`
+}
+
+func Response(w http.ResponseWriter, resp interface{}, err error) {
+ var body Body
+ if err != nil {
+ body.Code = -1
+ body.Msg = err.Error()
+ } else {
+ body.Msg = "OK"
+ body.Data = resp
+ }
+ httpx.OkJson(w, body)
+}
+```
+
+## 修改`handler`模板
+```shell
+$ vim ~/.goctl/api/handler.tpl
+```
+将模板替换为以下内容
+```go
+package handler
+
+import (
+ "net/http"
+ "greet/response"// ①
+
+ {{.ImportPackages}}
+)
+
+func {{.HandlerName}}(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ {{if .HasRequest}}var req types.{{.RequestType}}
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }{{end}}
+
+ l := logic.New{{.LogicType}}(r.Context(), ctx)
+ {{if .HasResp}}resp, {{end}}err := l.{{.Call}}({{if .HasRequest}}req{{end}})
+ {{if .HasResp}}reponse.Response(w, resp, err){{else}}reponse.Response(w, nil, err){{end}}//②
+
+ }
+}
+```
+
+① 替换为你真实的`response`包名，仅供参考
+
+② 自定义模板内容
+
+> [!TIP]
+>
+> 1.如果本地没有`~/.goctl/api/handler.tpl`文件，可以通过模板初始化命令`goctl template init`进行初始化
+
+## 修改模板前后对比
+* 修改前
+```go
+func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ var req types.Request
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }
+
+ l := logic.NewGreetLogic(r.Context(), ctx)
+ resp, err := l.Greet(req)
+ // 以下内容将被自定义模板替换
+ if err != nil {
+ httpx.Error(w, err)
+ } else {
+ httpx.OkJson(w, resp)
+ }
+ }
+}
+```
+* 修改后
+```go
+func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ var req types.Request
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }
+
+ l := logic.NewGreetLogic(r.Context(), ctx)
+ resp, err := l.Greet(req)
+ reponse.Response(w, resp, err)
+ }
+}
+```
+
+## 修改模板前后响应体对比
+
+* 修改前
+```json
+{
+ "message": "Hello go-zero!"
+}
+```
+
+* 修改后
+```json
+{
+ "code": 0,
+ "msg": "OK",
+ "data": {
+ "message": "Hello go-zero!"
+ }
+}
+```
+
+# 总结
+本文档仅对http相应为例讲述了自定义模板的流程，除此之外，自定义模板的场景还有：
+* model 层添加kmq
+* model 层生成待有效期option的model实例
+* http自定义相应格式
+ ...
diff --git a/doc/timingWheel.md b/go-zero.dev/cn/timing-wheel.md
similarity index 71%
rename from doc/timingWheel.md
rename to go-zero.dev/cn/timing-wheel.md
index 3d120b29..00c4d771 100644
--- a/doc/timingWheel.md
+++ b/go-zero.dev/cn/timing-wheel.md
@@ -1,20 +1,22 @@
-# go-zero 如何应对海量定时/延迟任务？
+# TimingWheel
-一个系统中存在着大量的调度任务，同时调度任务存在时间的滞后性，而大量的调度任务如果每一个都使用自己的调度器来管理任务的生命周期的话，浪费cpu的资源而且很低效。
+本文来介绍 `go-zero` 中 **延迟操作**。**延迟操作**，可以采用两个方案：
-本文来介绍 `go-zero` 中 **延迟操作**，它可能让开发者调度多个任务时，**只需关注具体的业务执行函数和执行时间「立即或者延迟」**。而 **延迟操作**，通常可以采用两个方案：
1. `Timer`：定时器维护一个优先队列，到时间点执行，然后把需要执行的 task 存储在 map 中
2. `collection` 中的 `timingWheel` ，维护一个存放任务组的数组，每一个槽都维护一个存储task的双向链表。开始执行时，计时器每隔指定时间执行一个槽里面的tasks。
+
+
方案2把维护task从 `优先队列 O(nlog(n))` 降到 `双向链表 O(1)`，而执行task也只要轮询一个时间点的tasks `O(N)`，不需要像优先队列，放入和删除元素 `O(nlog(n))`。
-我们先看看 `go-zero` 中自己对 `timingWheel` 的使用 ：
## cache 中的 timingWheel
+
首先我们先来在 `collection` 的 `cache` 中关于 `timingWheel` 的使用：
+
```go
timingWheel, err := NewTimingWheel(time.Second, slots, func(k, v interface{}) {
key, ok := k.(string)
@@ -30,18 +32,25 @@ if err != nil {
cache.timingWheel = timingWheel
```
+
这是 `cache` 初始化中也同时初始化 `timingWheel` 做key的过期处理，参数依次代表：
+
- `interval`：时间划分刻度
- `numSlots`：时间槽
- `execute`：时间点执行函数
+
+
在 `cache` 中执行函数则是 **删除过期key**，而这个过期则由 `timingWheel` 来控制推进时间。
+
**接下来，就通过 `cache` 对 `timingWheel` 的使用来认识。**
+
### 初始化
+
```go
// 真正做初始化
func newTimingWheelWithClock(interval time.Duration, numSlots int, execute Execute, ticker timex.Ticker) (
@@ -69,11 +78,15 @@ func newTimingWheelWithClock(interval time.Duration, numSlots int, execute Execu
}
```
-
+
+
+
以上比较直观展示 `timingWheel` 的 **“时间轮”**，后面会围绕这张图解释其中推进的细节。
- `go tw.run()` 开一个协程做时间推动：
+
+`go tw.run()` 开一个协程做时间推动：
+
```go
func (tw *TimingWheel) run() {
@@ -91,14 +104,19 @@ func (tw *TimingWheel) run() {
}
```
-可以看出，在初始化的时候就开始了 `timer` 执行，并以`internal`时间段转动，然后底层不停的获取来自 `slot` 中的 `list` 的task，交给 `execute` 执行。
-
+可以看出，在初始化的时候就开始了 `timer` 执行，并以`internal`时间段转动，然后底层不停的获取来自 `slot` 中的 `list` 的task，交给 `execute` 执行。
+
+
+
+
### Task Operation
+
紧接着就是设置 `cache key` ：
+
```go
func (c *Cache) Set(key string, value interface{}) {
c.lock.Lock()
@@ -116,23 +134,30 @@ func (c *Cache) Set(key string, value interface{}) {
}
```
+
1. 先看在 `data map` 中有没有存在这个key
-2. 存在，则更新 `expire` -> `MoveTimer()`
-3. 第一次设置key -> `SetTimer()`
+2. 存在，则更新 `expire` -> `MoveTimer()`
+3. 第一次设置key -> `SetTimer()`
+
+
所以对于 `timingWheel` 的使用上就清晰了，开发者根据需求可以 `add` 或是 `update`。
+
同时我们跟源码进去会发现：`SetTimer() MoveTimer()` 都是将task输送到channel，由 `run()` 中开启的协程不断取出 `channel` 的task操作。
+
> `SetTimer() -> setTask()`：
->
> - not exist task：`getPostion -> pushBack to list -> setPosition`
-> - exist task：`get from timers -> moveTask() `
+> - exist task：`get from timers -> moveTask()`
>
-> `MoveTimer() -> moveTask()`
+`MoveTimer() -> moveTask()`
+
+
由上面的调用链，有一个都会调用的函数：`moveTask()`
+
```go
func (tw *TimingWheel) moveTask(task baseEntry) {
// timers: Map => 通过key获取 [positionEntry「pos, task」]
@@ -142,7 +167,7 @@ func (tw *TimingWheel) moveTask(task baseEntry) {
}
timer := val.(*positionEntry)
- // {delay < interval} => 延迟时间比一个时间格间隔还小，没有更小的刻度，说明任务应该立即执行
+ // {delay < interval} => 延迟时间比一个时间格间隔还小，没有更小的刻度，说明任务应该立即执行
if task.delay < tw.interval {
threading.GoSafe(func() {
tw.execute(timer.item.key, timer.item.value)
@@ -153,7 +178,7 @@ func (tw *TimingWheel) moveTask(task baseEntry) {
pos, circle := tw.getPositionAndCircle(task.delay)
if pos >= timer.pos {
timer.item.circle = circle
- // 记录前后的移动offset。为了后面过程重新入队
+ // 记录前后的移动offset。为了后面过程重新入队
timer.item.diff = pos - timer.pos
} else if circle > 0 {
// 转移到下一层，将 circle 转换为 diff 一部分
@@ -175,31 +200,39 @@ func (tw *TimingWheel) moveTask(task baseEntry) {
}
```
+
以上过程有以下几种情况：
+
- `delay < internal`：因为 < 单个时间精度，表示这个任务已经过期，需要马上执行
- 针对改变的 `delay`：
- - `new >= old`：`
+而时间分隔上，时间轮有 `circle` 分层，这样就可以不断复用原有的 `numSlots` ，因为定时器在不断 `loop`，而执行可以把上层的 `slot` 下降到下层，在不断 `loop` 中就可以执行到上层的task。
-## 参考资料
-- [go-zero](https://github.com/tal-tech/go-zero)
-- [go-zero 文档](https://www.yuque.com/tal-tech/go-zero)
-- [go-zero中 collection.Cache](https://github.com/zeromicro/zero-doc/blob/main/doc/collection.md)
+在 `go-zero` 中还有很多实用的组件工具，用好工具对于提升服务性能和开发效率都有很大的帮助，希望本篇文章能给大家带来一些收获。
diff --git a/go-zero.dev/cn/tips.md b/go-zero.dev/cn/tips.md
new file mode 100644
index 00000000..0b6ae02e
--- /dev/null
+++ b/go-zero.dev/cn/tips.md
@@ -0,0 +1,6 @@
+# 阅读须知
+
+本文档从快速入门，详细项目开发流程，go-zero服务设计思想，goctl工具的使用等维度进行了介绍，
+对于刚刚接触go或go-zero的同学需要把这些篇幅都看完才能有所了解，因此有些费力，这里建议大家阅读的方法。
+* 保持耐心跟着文档目录进行，文档是按照从简单到深入的渐进式过程编写的。
+* 在遇到问题或错误时，请一定记住多查[FAQ](faq.md)。
diff --git a/go-zero.dev/cn/tokenlimit.md b/go-zero.dev/cn/tokenlimit.md
new file mode 100644
index 00000000..92912c15
--- /dev/null
+++ b/go-zero.dev/cn/tokenlimit.md
@@ -0,0 +1,152 @@
+# tokenlimit
+本节将通过令牌桶限流（tokenlimit）来介绍其基本使用。
+
+## 使用
+
+```go
+const (
+ burst = 100
+ rate = 100
+ seconds = 5
+)
+
+store := redis.NewRedis("localhost:6379", "node", "")
+fmt.Println(store.Ping())
+// New tokenLimiter
+limiter := limit.NewTokenLimiter(rate, burst, store, "rate-test")
+timer := time.NewTimer(time.Second * seconds)
+quit := make(chan struct{})
+defer timer.Stop()
+go func() {
+ <-timer.C
+ close(quit)
+}()
+
+var allowed, denied int32
+var wait sync.WaitGroup
+for i := 0; i < runtime.NumCPU(); i++ {
+ wait.Add(1)
+ go func() {
+ for {
+ select {
+ case <-quit:
+ wait.Done()
+ return
+ default:
+ if limiter.Allow() {
+ atomic.AddInt32(&allowed, 1)
+ } else {
+ atomic.AddInt32(&denied, 1)
+ }
+ }
+ }
+ }()
+}
+
+wait.Wait()
+fmt.Printf("allowed: %d, denied: %d, qps: %d\n", allowed, denied, (allowed+denied)/seconds)
+```
+
+
+## tokenlimit
+
+从整体上令牌桶生产token逻辑如下：
+- 用户配置的平均发送速率为r，则每隔1/r秒一个令牌被加入到桶中；
+- 假设桶中最多可以存放b个令牌。如果令牌到达时令牌桶已经满了，那么这个令牌会被丢弃；
+- 当流量以速率v进入，从桶中以速率v取令牌，拿到令牌的流量通过，拿不到令牌流量不通过，执行熔断逻辑；
+
+
+
+`go-zero` 在两类限流器下都采取 `lua script` 的方式，依赖redis可以做到分布式限流，`lua script`同时可以做到对 token 生产读取操作的原子性。
+
+下面来看看 `lua script` 控制的几个关键属性：
+
+| argument | mean |
+| --- | --- |
+| ARGV[1] | rate 「每秒生成几个令牌」 |
+| ARGV[2] | burst 「令牌桶最大值」 |
+| ARGV[3] | now_time「当前时间戳」 |
+| ARGV[4] | get token nums 「开发者需要获取的token数」 |
+| KEYS[1] | 表示资源的tokenkey |
+| KEYS[2] | 表示刷新时间的key |
+
+
+
+```lua
+-- 返回是否可以活获得预期的token
+
+local rate = tonumber(ARGV[1])
+local capacity = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local requested = tonumber(ARGV[4])
+
+-- fill_time：需要填满 token_bucket 需要多久
+local fill_time = capacity/rate
+-- 将填充时间向下取整
+local ttl = math.floor(fill_time*2)
+
+-- 获取目前 token_bucket 中剩余 token 数
+-- 如果是第一次进入，则设置 token_bucket 数量为 令牌桶最大值
+local last_tokens = tonumber(redis.call("get", KEYS[1]))
+if last_tokens == nil then
+ last_tokens = capacity
+end
+
+-- 上一次更新 token_bucket 的时间
+local last_refreshed = tonumber(redis.call("get", KEYS[2]))
+if last_refreshed == nil then
+ last_refreshed = 0
+end
+
+local delta = math.max(0, now-last_refreshed)
+-- 通过当前时间与上一次更新时间的跨度，以及生产token的速率，计算出新的token数
+-- 如果超过 max_burst，多余生产的token会被丢弃
+local filled_tokens = math.min(capacity, last_tokens+(delta*rate))
+local allowed = filled_tokens >= requested
+local new_tokens = filled_tokens
+if allowed then
+ new_tokens = filled_tokens - requested
+end
+
+-- 更新新的token数，以及更新时间
+redis.call("setex", KEYS[1], ttl, new_tokens)
+redis.call("setex", KEYS[2], ttl, now)
+
+return allowed
+```
+
+
+上述可以看出 `lua script` ：只涉及对 token 操作，保证 token 生产合理和读取合理。
+
+
+## 函数分析
+
+
+
+
+
+从上述流程中看出：
+
+
+1. 有多重保障机制，保证限流一定会完成。
+1. 如果`redis limiter`失效，至少在进程内`rate limiter`兜底。
+1. 重试 `redis limiter` 机制保证尽可能地正常运行。
+
+
+
+## 总结
+
+
+`go-zero` 中的 `tokenlimit` 限流方案适用于瞬时流量冲击，现实请求场景并不以恒定的速率。令牌桶相当预请求，当真实的请求到达不至于瞬间被打垮。当流量冲击到一定程度，则才会按照预定速率进行消费。
+
+
+但是生产`token`上，不能按照当时的流量情况作出动态调整，不够灵活，还可以进行进一步优化。此外可以参考[Token bucket WIKI](https://en.wikipedia.org/wiki/Token_bucket) 中提到分层令牌桶，根据不同的流量带宽，分至不同排队中。
+
+
+## 参考
+
+- [go-zero tokenlimit](https://github.com/zeromicro/go-zero/blob/master/core/limit/tokenlimit.go)
+- [Go-Redis 提供的分布式限流库](https://github.com/go-redis/redis_rate)
+
+
+
diff --git a/go-zero.dev/cn/tool-center.md b/go-zero.dev/cn/tool-center.md
new file mode 100644
index 00000000..a6c6531f
--- /dev/null
+++ b/go-zero.dev/cn/tool-center.md
@@ -0,0 +1,5 @@
+# 工具中心
+在go-zero中，提供了很多提高工程效率的工具，如api，rpc生成，在此基础之上，api文件的编写就显得那么的无力，
+因为缺少了高亮，代码提示，模板生成等，本节将带你了解go-zero是怎么解决这些难题的，本节包含以下小节：
+* [intellij插件](intellij.md)
+* [vscode插件](vscode.md)
\ No newline at end of file
diff --git a/go-zero.dev/cn/trace.md b/go-zero.dev/cn/trace.md
new file mode 100644
index 00000000..3d850e22
--- /dev/null
+++ b/go-zero.dev/cn/trace.md
@@ -0,0 +1,185 @@
+# go-zero链路追踪
+
+## 序言
+
+微服务架构中，调用链可能很漫长，从 `http` 到 `rpc` ，又从 `rpc` 到 `http` 。而开发者想了解每个环节的调用情况及性能，最佳方案就是 **全链路跟踪**。
+
+追踪的方法就是在一个请求开始时生成一个自己的 `spanID` ，随着整个请求链路传下去。我们则通过这个 `spanID` 查看整个链路的情况和性能问题。
+
+下面来看看 `go-zero` 的链路实现。
+
+## 代码结构
+
+- [spancontext](https://github.com/zeromicro/go-zero/blob/master/core/trace/spancontext.go) ：保存链路的上下文信息「traceid，spanid，或者是其他想要传递的内容」
+- [span](https://github.com/zeromicro/go-zero/blob/master/core/trace/span.go) ：链路中的一个操作，存储时间和某些信息
+- [propagator](https://github.com/zeromicro/go-zero/blob/master/core/trace/propagator.go) ： `trace` 传播下游的操作「抽取，注入」
+- [noop](https://github.com/zeromicro/go-zero/blob/master/core/trace/noop.go) ：实现了空的 `tracer` 实现
+
+
+
+## 概念
+
+### SpanContext
+
+在介绍 `span` 之前，先引入 `context` 。SpanContext 保存了分布式追踪的上下文信息，包括 Trace id，Span id 以及其它需要传递到下游的内容。OpenTracing 的实现需要将 SpanContext 通过某种协议 进行传递，以将不同进程中的 Span 关联到同一个 Trace 上。对于 HTTP 请求来说，SpanContext 一般是采用 HTTP header 进行传递的。
+
+下面是 `go-zero` 默认实现的 `spanContext`
+
+```go
+type spanContext struct {
+ traceId string // TraceID 表示tracer的全局唯一ID
+ spanId string // SpanId 标示单个trace中某一个span的唯一ID，在trace中唯一
+}
+```
+
+同时开发者也可以实现 `SpanContext` 提供的接口方法，实现自己的上下文信息传递：
+
+```go
+type SpanContext interface {
+ TraceId() string // get TraceId
+ SpanId() string // get SpanId
+ Visit(fn func(key, val string) bool) // 自定义操作TraceId，SpanId
+}
+```
+
+### Span
+
+一个 REST 调用或者数据库操作等，都可以作为一个 `span` 。 `span` 是分布式追踪的最小跟踪单位，一个 Trace 由多段 Span 组成。追踪信息包含如下信息：
+
+```go
+type Span struct {
+ ctx spanContext // 传递的上下文
+ serviceName string // 服务名
+ operationName string // 操作
+ startTime time.Time // 开始时间戳
+ flag string // 标记开启trace是 server 还是 client
+ children int // 本 span fork出来的 childsnums
+}
+```
+
+从 `span` 的定义结构来看：在微服务中， 这就是一个完整的子调用过程，有调用开始 `startTime` ，有标记自己唯一属性的上下文结构 `spanContext` 以及 fork 的子节点数。
+
+## 实例应用
+
+在 `go-zero` 中http，rpc中已经作为内置中间件集成。我们以 [http](https://github.com/zeromicro/go-zero/blob/master/rest/handler/tracinghandler.go) ，[rpc](https://github.com/zeromicro/go-zero/blob/master/zrpc/internal/clientinterceptors/tracinginterceptor.go) 中，看看 `tracing` 是怎么使用的：
+
+### HTTP
+
+```go
+func TracingHandler(next http.Handler) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ // **1**
+ carrier, err := trace.Extract(trace.HttpFormat, r.Header)
+ // ErrInvalidCarrier means no trace id was set in http header
+ if err != nil && err != trace.ErrInvalidCarrier {
+ logx.Error(err)
+ }
+
+ // **2**
+ ctx, span := trace.StartServerSpan(r.Context(), carrier, sysx.Hostname(), r.RequestURI)
+ defer span.Finish()
+ // **5**
+ r = r.WithContext(ctx)
+
+ next.ServeHTTP(w, r)
+ })
+}
+
+func StartServerSpan(ctx context.Context, carrier Carrier, serviceName, operationName string) (
+ context.Context, tracespec.Trace) {
+ span := newServerSpan(carrier, serviceName, operationName)
+ // **4**
+ return context.WithValue(ctx, tracespec.TracingKey, span), span
+}
+
+func newServerSpan(carrier Carrier, serviceName, operationName string) tracespec.Trace {
+ // **3**
+ traceId := stringx.TakeWithPriority(func() string {
+ if carrier != nil {
+ return carrier.Get(traceIdKey)
+ }
+ return ""
+ }, func() string {
+ return stringx.RandId()
+ })
+ spanId := stringx.TakeWithPriority(func() string {
+ if carrier != nil {
+ return carrier.Get(spanIdKey)
+ }
+ return ""
+ }, func() string {
+ return initSpanId
+ })
+
+ return &Span{
+ ctx: spanContext{
+ traceId: traceId,
+ spanId: spanId,
+ },
+ serviceName: serviceName,
+ operationName: operationName,
+ startTime: timex.Time(),
+ // 标记为server
+ flag: serverFlag,
+ }
+}
+```
+
+1. 将 header -> carrier，获取 header 中的traceId等信息
+2. 开启一个新的 span，并把**「traceId，spanId」**封装在context中
+3. 从上述的 carrier「也就是header」获取traceId，spanId
+ - 看header中是否设置
+ - 如果没有设置，则随机生成返回
+4. 从 `request` 中产生新的ctx，并将相应的信息封装在 ctx 中，返回
+5. 从上述的 context，拷贝一份到当前的 `request`
+
+
+
+这样就实现了 `span` 的信息随着 `request` 传递到下游服务。
+
+### RPC
+
+在 rpc 中存在 `client, server` ，所以从 `tracing` 上也有 `clientTracing, serverTracing` 。 `serveTracing` 的逻辑基本与 http 的一致，来看看 `clientTracing` 是怎么使用的？
+
+```go
+func TracingInterceptor(ctx context.Context, method string, req, reply interface{},
+ cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
+ // open clientSpan
+ ctx, span := trace.StartClientSpan(ctx, cc.Target(), method)
+ defer span.Finish()
+
+ var pairs []string
+ span.Visit(func(key, val string) bool {
+ pairs = append(pairs, key, val)
+ return true
+ })
+ // **3** 将 pair 中的data以map的形式加入 ctx
+ ctx = metadata.AppendToOutgoingContext(ctx, pairs...)
+
+ return invoker(ctx, method, req, reply, cc, opts...)
+}
+
+func StartClientSpan(ctx context.Context, serviceName, operationName string) (context.Context, tracespec.Trace) {
+ // **1**
+ if span, ok := ctx.Value(tracespec.TracingKey).(*Span); ok {
+ // **2**
+ return span.Fork(ctx, serviceName, operationName)
+ }
+
+ return ctx, emptyNoopSpan
+}
+```
+
+1. 获取上游带下来的 span 上下文信息
+2. 从获取的 span 中创建新的 ctx，span「继承父span的traceId」
+3. 将生成 span 的data加入ctx，传递到下一个中间件，流至下游
+
+## 总结
+
+`go-zero` 通过拦截请求获取链路traceID，然后在中间件函数入口会分配一个根Span，然后在后续操作中会分裂出子Span，每个span都有自己的具体的标识，Finsh之后就会汇集在链路追踪系统中。开发者可以通过 `ELK` 工具追踪 `traceID` ，看到整个调用链。
+
+同时 `go-zero` 并没有提供整套 `trace` 链路方案，开发者可以封装 `go-zero` 已有的 `span` 结构，做自己的上报系统，接入 `jaeger, zipkin` 等链路追踪工具。
+
+## 参考
+
+- [go-zero trace](https://github.com/zeromicro/go-zero/tree/master/core/trace)
\ No newline at end of file
diff --git a/go-zero.dev/cn/vscode.md b/go-zero.dev/cn/vscode.md
new file mode 100644
index 00000000..2e5ef0d4
--- /dev/null
+++ b/go-zero.dev/cn/vscode.md
@@ -0,0 +1,47 @@
+# vs code 插件
+该插件可以安装在 1.46.0+ 版本的 Visual Studio Code 上，首先请确保你的 Visual Studio Code 版本符合要求，并已安装 goctl 命令行工具。如果尚未安装 Visual Studio Code，请安装并打开 Visual Studio Code。 导航到“扩展”窗格，搜索 goctl 并安装此扩展（发布者ID为 “xiaoxin-technology.goctl”）。
+
+Visual Studio Code 扩展使用请参考[这里](https://code.visualstudio.com/docs/editor/extension-gallery)。
+
+## 功能列表
+
+已实现功能
+
+* 语法高亮
+* 跳转到定义/引用
+* 代码格式化
+* 代码块提示
+
+未实现功能:
+
+* 语法错误检查
+* 跨文件代码跳转
+* goctl 命令行调用
+
+### 语法高亮
+
+### 代码跳转
+
+
+
+### 代码格式化
+
+调用 goctl 命令行格式化工具，使用前请确认 goctl 已加入 `$PATH` 且有可执行权限
+
+### 代码块提示
+
+#### info 代码块
+
+
+
+#### type 代码块
+
+
+
+#### service 代码块
+
+
+
+#### handler 代码块
+
+
diff --git a/go-zero.dev/cn/wechat.md b/go-zero.dev/cn/wechat.md
new file mode 100644
index 00000000..24ab835b
--- /dev/null
+++ b/go-zero.dev/cn/wechat.md
@@ -0,0 +1,27 @@
+# 公众号
+微服务实战是go-zero的官方公众号，在这里会发布最新的go-zero最佳实践，同步go夜读、go开源说、GopherChina、腾讯云开发者大会等多渠道关于go-zero的最新技术和资讯。
+
+| 公众号名称 | +公众号作者 | +公众号二维码 | +
| 微服务实战 | +kevwan | + |
+
+
+# go-zero
+
+[](https://github.com/zeromicro/go-zero/actions)
+[](https://codecov.io/gh/tal-tech/go-zero)
+[](https://goreportcard.com/report/github.com/tal-tech/go-zero)
+[](https://github.com/zeromicro/go-zero)
+[](https://opensource.org/licenses/MIT)
+
+## 0. what is go-zero
+
+go-zero is a web and rpc framework that with lots of engineering practices builtin. It’s born to ensure the stability of the busy services with resilience design, and has been serving sites with tens of millions users for years.
+
+go-zero contains simple API description syntax and code generation tool called `goctl`. You can generate Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript from .api files with `goctl`.
+
+Advantages of go-zero:
+
+* improve the stability of the services with tens of millions of daily active users
+* builtin chained timeout control, concurrency control, rate limit, adaptive circuit breaker, adaptive load shedding, even no configuration needed
+* builtin middlewares also can be integrated into your frameworks
+* simple API syntax, one command to generate couple of different languages
+* auto validate the request parameters from clients
+* plenty of builtin microservice management and concurrent toolkits
+
+
+
+## 1. Backgrounds of go-zero
+
+At the beginning of 2018, we decided to re-design our system, from monolithic architecture with Java+MongoDB to microservice architecture. After researches and comparison, we chose to:
+
+* Golang based
+ * great performance
+ * simple syntax
+ * proven engineering efficiency
+ * extreme deployment experience
+ * less server resource consumption
+* Self-designed microservice architecture
+ * I have rich experience on designing microservice architectures
+ * easy to location the problems
+ * easy to extend the features
+
+## 2. Design considerations on go-zero
+
+By designing the microservice architecture, we expected to ensure the stability, as well as the productivity. And from just the beginning, we have the following 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 monolithic system to microservice system, and deployed on August 2018. The new system guaranteed the business growth, and the system stability.
+
+## 3. 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:
+
+* 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 couple layers and mechanisms:
+
+
+
+## 4. Future development plans of go-zero
+
+* auto generate API mock server, make the client debugging easier
+* auto generate the simple integration test for the server side just from the .api files
+
+## 5. Installation
+
+Run the following command under your project:
+
+```shell
+go get -u github.com/tal-tech/go-zero
+```
+
+## 6. Quick Start
+
+0. full examples can be checked out from below:
+
+ [Rapid development of microservice systems](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl-en.md)
+
+ [Rapid development of microservice systems - multiple RPCs](https://github.com/tal-tech/zero-doc/blob/main/doc/bookstore-en.md)
+
+1. 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 the productivity, and make our lives easier.
+
+ ```shell
+ GO111MODULE=on go get -u github.com/tal-tech/go-zero/tools/goctl
+ ```
+
+ make sure goctl is executable.
+
+2. create the API file, like greet.api, you can install the plugin of goctl in vs code, api syntax is supported.
+
+ ```go
+ type Request struct {
+ Name string `path:"name,options=you|me"` // parameters are auto validated
+ }
+
+ type Response struct {
+ Message string `json:"message"`
+ }
+
+ service greet-api {
+ @handler GreetHandler
+ get /greet/from/:name(Request) returns (Response);
+ }
+ ```
+
+ the .api files also can be generate by goctl, like below:
+
+ ```shell
+ goctl api -o greet.api
+ ```
+
+3. generate the go server side code
+
+ ```shell
+ goctl api go -api greet.api -dir greet
+ ```
+
+ the generated files look like:
+
+ ```
+ ├── greet
+ │ ├── etc
+ │ │ └── greet-api.yaml // configuration file
+ │ ├── greet.go // main file
+ │ └── internal
+ │ ├── config
+ │ │ └── config.go // configuration definition
+ │ ├── handler
+ │ │ ├── greethandler.go // get/put/post/delete routes are defined here
+ │ │ └── routes.go // routes list
+ │ ├── logic
+ │ │ └── greetlogic.go // request logic can be written here
+ │ ├── svc
+ │ │ └── servicecontext.go // service context, mysql/redis can be passed in here
+ │ └── types
+ │ └── types.go // request/response defined here
+ └── greet.api // api description file
+ ```
+
+ the generated code can be run directly:
+
+ ```shell
+ cd greet
+ go mod init
+ go mod tidy
+ go run greet.go -f etc/greet-api.yaml
+ ```
+
+ by default, it’s listening on port 8888, while it can be changed in configuration file.
+
+ you can check it by curl:
+
+ ```shell
+ curl -i http://localhost:8888/greet/from/you
+ ```
+
+ the response looks like:
+
+ ```http
+ HTTP/1.1 200 OK
+ Date: Sun, 30 Aug 2020 15:32:35 GMT
+ Content-Length: 0
+ ```
+
+4. Write the business logic code
+
+ * the dependencies can be passed into the logic within servicecontext.go, like mysql, reds etc.
+ * add the logic code in logic package according to .api file
+
+5. Generate code like Java, TypeScript, Dart, JavaScript etc. just from the api file
+
+ ```shell
+ goctl api java -api greet.api -dir greet
+ goctl api dart -api greet.api -dir greet
+ ...
+ ```
+
+## 7. Benchmark
+
+
+
+[Checkout the test code](https://github.com/smallnest/go-web-framework-benchmark)
+
+## 8. Documents (adding)
+
+* [Rapid development of microservice systems](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl-en.md)
+* [Rapid development of microservice systems - multiple RPCs](https://github.com/tal-tech/zero-doc/blob/main/docs/zero/bookstore-en.md)
+* [Examples](https://github.com/zeromicro/zero-examples)
+
+## 9. Important notes
+
+* Use grpc 1.29.1, because etcd lib doesn’t support latter versions.
+
+ `google.golang.org/grpc v1.29.1`
+
+* For protobuf compatibility, use `protocol-gen@v1.3.2`.
+
+ ` go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2`
+
+## 10. Chat group
+
+Join the chat via https://join.slack.com/t/go-zeroworkspace/shared_invite/zt-m39xssxc-kgIqERa7aVsujKNj~XuPKg
diff --git a/go-zero.dev/en/about-us.md b/go-zero.dev/en/about-us.md
new file mode 100644
index 00000000..b3860771
--- /dev/null
+++ b/go-zero.dev/en/about-us.md
@@ -0,0 +1,21 @@
+# About Us
+
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## Go-Zero
+go-zero is a web and rpc framework that integrates various engineering practices. Through flexible design, the stability of the large concurrent server is guaranteed, and it has withstood full actual combat tests.
+
+go-zero contains a minimalist API definition and generation tool goctl, which can generate Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript code with one click according to the defined api file, and run it directly.
+
+## Go-Zero's Author
+[
](https://github.com/kevwan)
+
+**kevwan** is the XiaoHeiBan’s R&D person in charge and a senior technical expert in TAL, whhas 14 years of R&D team management experience, 16 years of architecture design experience, 20 years of engineering practical experience, responsible for the architecture design of many large-scale projects, and has been in partnership for many times (acquired ), Lecturer of Gopher China Conference, Lecturer of Tencent Cloud Developer Conference.
+
+## Go-Zero Members
+As of February 2021, go-zero currently has 30 team developers and 50+ community members.
+
+## Go-Zero Community
+We currently have more than 3,000 community members. Here, you can discuss any go-zero technology, feedback on issues, get the latest go-zero information, and the technical experience shared by the big guys every day.
+
diff --git a/go-zero.dev/en/api-coding.md b/go-zero.dev/en/api-coding.md
new file mode 100644
index 00000000..2215fe6c
--- /dev/null
+++ b/go-zero.dev/en/api-coding.md
@@ -0,0 +1,57 @@
+# API File Coding
+
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## Create file
+```shell
+$ vim service/user/cmd/api/user.api
+```
+```text
+type (
+ LoginReq {
+ Username string `json:"username"`
+ Password string `json:"password"`
+ }
+
+ LoginReply {
+ Id int64 `json:"id"`
+ Name string `json:"name"`
+ Gender string `json:"gender"`
+ AccessToken string `json:"accessToken"`
+ AccessExpire int64 `json:"accessExpire"`
+ RefreshAfter int64 `json:"refreshAfter"`
+ }
+)
+
+service user-api {
+ @handler login
+ post /user/login (LoginReq) returns (LoginReply)
+}
+```
+## Generate api service
+### By goctl executable file
+
+```shell
+$ cd book/service/user/cmd/api
+$ goctl api go -api user.api -dir .
+```
+```text
+Done.
+```
+
+### By Intellij Plugin
+
+Right-click on the `user.api` file, and then click to enter `New`->`Go Zero`->`Api Code`, enter the target directory selection, that is, the target storage directory of the api source code, the default is the directory where user.api is located, select Click OK after finishing the list.
+
+
+
+
+### By Keymap
+
+Open user.api, enter the editing area, use the shortcut key `Command+N` (for macOS) or `alt+insert` (for windows), select `Api Code`, and also enter the directory selection pop-up window, after selecting the directory Just click OK.
+
+# Guess you wants
+* [API IDL](api-grammar.md)
+* [API Commands](goctl-api.md)
+* [API Directory Structure](api-dir.md)
\ No newline at end of file
diff --git a/go-zero.dev/en/api-config.md b/go-zero.dev/en/api-config.md
new file mode 100644
index 00000000..7959fd5f
--- /dev/null
+++ b/go-zero.dev/en/api-config.md
@@ -0,0 +1,112 @@
+# API configuration
+
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+The api configuration controls various functions in the api service, including but not limited to the service listening address, port, environment configuration, log configuration, etc. Let's take a simple configuration to see what the common configurations in the api do.
+
+## Configuration instructions
+Through the yaml configuration, we will find that there are many parameters that we are not aligned with config. This is because many of the config definitions are labeled with `optional` or `default`. For `optional` options, you can choose according to your own Need to determine whether it needs to be set. For the `default` tag, if you think the default value is enough, you don't need to set it. Generally, the value in `default` basically does not need to be modified and can be considered as a best practice value.
+
+### Config
+
+```go
+type Config struct{
+ rest.RestConf // rest api configuration
+ Auth struct { // jwt authentication configuration
+ AccessSecret string // jwt key
+ AccessExpire int64 // jwt expire, unit: second
+ }
+ Mysql struct { // database configuration, in addition to mysql, there may be other databases such as mongo
+ DataSource string // mysql datasource, which satisfies the format of user:password@tcp(ip:port)db?queries
+ }
+ CacheRedis cache.CacheConf // redis cache
+ UserRpc zrpc.RpcClientConf // rpc client configuration
+}
+```
+
+### rest.RestConf
+The basic configuration of api service, including monitoring address, monitoring port, certificate configuration, current limit, fusing parameters, timeout parameters and other controls, expand it, we can see:
+```go
+service.ServiceConf // service configuration
+Host string `json:",default=0.0.0.0"` // http listening ip, default 0.0.0.0
+Port int // http listening port, required
+CertFile string `json:",optional"` // https certificate file, optional
+KeyFile string `json:",optional"` // https private key file, optional
+Verbose bool `json:",optional"` // whether to print detailed http request log
+MaxConns int `json:",default=10000"` // http can accept the maximum number of requests at the same time (current limit), the default is 10000
+MaxBytes int64 `json:",default=1048576,range=[0:8388608]"` // http can accept the maximum Content Length of the request, the default is 1048576, and the set value cannot be between 0 and 8388608
+// milliseconds
+Timeout int64 `json:",default=3000"` // timeout duration control, unit: milliseconds, default 3000
+CpuThreshold int64 `json:",default=900,range=[0:1000]"` // CPU load reduction threshold, the default is 900, the allowable setting range is 0 to 1000
+Signature SignatureConf `json:",optional"` // signature configuration
+```
+
+### service.ServiceConf
+```go
+type ServiceConf struct {
+ Name string // service name
+ Log logx.LogConf // log configuration
+ Mode string `json:",default=pro,options=dev|test|pre|pro"` // service environment, dev-development environment, test-test environment, pre-pre-release environment, pro-formal environment
+ MetricsUrl string `json:",optional"` // index report interface address, this address needs to support post json
+ Prometheus prometheus.Config `json:",optional"` // prometheus configuration
+}
+```
+
+### logx.LogConf
+```go
+type LogConf struct {
+ ServiceName string `json:",optional"` // service name
+ Mode string `json:",default=console,options=console|file|volume"` // Log mode, console-output to console, file-output to the current server (container) file, volume-output docker hangs in the file
+ Path string `json:",default=logs"` // Log storage path
+ Level string `json:",default=info,options=info|error|severe"` // Log level
+ Compress bool `json:",optional"` // whether to enable gzip compression
+ KeepDays int `json:",optional"` // log retention days
+ StackCooldownMillis int `json:",default=100"` // log write interval
+}
+```
+
+### prometheus.Config
+```go
+type Config struct {
+ Host string `json:",optional"` // prometheus monitor host
+ Port int `json:",default=9101"` // prometheus listening port
+ Path string `json:",default=/metrics"` // report address
+}
+```
+
+### SignatureConf
+```go
+SignatureConf struct {
+ Strict bool `json:",default=false"` // Whether it is Strict mode, if it is, Private Keys is required
+ Expiry time.Duration `json:",default=1h"` // Validity period, default is 1 hour
+ PrivateKeys []PrivateKeyConf // Signing key related configuration
+}
+```
+
+### PrivateKeyConf
+```go
+PrivateKeyConf struct {
+ Fingerprint string // Fingerprint configuration
+ KeyFile string // Key configuration
+}
+```
+
+### cache.CacheConf
+```go
+ClusterConf []NodeConf
+
+NodeConf struct {
+ redis.RedisConf
+ Weight int `json:",default=100"` // Weights
+}
+```
+
+### redis.RedisConf
+```go
+RedisConf struct {
+ Host string // redis address
+ Type string `json:",default=node,options=node|cluster"` // redis type
+ Pass string `json:",optional"` // redis password
+}
+```
diff --git a/go-zero.dev/en/api-dir.md b/go-zero.dev/en/api-dir.md
new file mode 100644
index 00000000..cdbe1f0d
--- /dev/null
+++ b/go-zero.dev/en/api-dir.md
@@ -0,0 +1,27 @@
+# API directory introduction
+
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+```text
+.
+├── etc
+│ └── greet-api.yaml // yaml configuration file
+├── go.mod // go module file
+├── greet.api // api interface description language file
+├── greet.go // main function entry
+└── internal
+ ├── config
+ │ └── config.go // configuration declaration type
+ ├── handler // routing and handler forwarding
+ │ ├── greethandler.go
+ │ └── routes.go
+ ├── logic // business logic
+ │ └── greetlogic.go
+ ├── middleware // middleware file
+ │ └── greetmiddleware.go
+ ├── svc // the resource pool that logic depends on
+ │ └── servicecontext.go
+ └── types // The struct of request and response is automatically generated according to the api, and editing is not recommended
+ └── types.go
+```
\ No newline at end of file
diff --git a/go-zero.dev/en/api-grammar.md b/go-zero.dev/en/api-grammar.md
new file mode 100644
index 00000000..64676cf6
--- /dev/null
+++ b/go-zero.dev/en/api-grammar.md
@@ -0,0 +1,743 @@
+# API syntax
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## API IDL example
+
+```go
+/**
+ * api syntax example and syntax description
+ */
+
+// api syntax version
+syntax = "v1"
+
+// import literal
+import "foo.api"
+
+// import group
+import (
+ "bar.api"
+ "foo/bar.api"
+)
+info(
+ author: "anqiansong"
+ date: "2020-01-08"
+ desc: "api syntax example and syntax description"
+)
+
+// type literal
+
+type Foo{
+ Foo int `json:"foo"`
+}
+
+// type group
+
+type(
+ Bar{
+ Bar int `json:"bar"`
+ }
+)
+
+// service block
+@server(
+ jwt: Auth
+ group: foo
+)
+service foo-api{
+ @doc "foo"
+ @handler foo
+ post /foo (Foo) returns (Bar)
+}
+```
+
+## API syntax structure
+
+* syntax statement
+* import syntax block
+* info syntax block
+* type syntax block
+* service syntax block
+* hidden channel
+
+> [!TIP]
+> In the above grammatical structure, grammatically speaking, each grammar block can be declared anywhere in the .api file according to the grammatical block.> But in order to improve reading efficiency, we suggest to declare in the above order, because it may be in the future Strict mode is used to control the order of syntax blocks.
+
+### syntax statement
+
+syntax is a newly added grammatical structure, the introduction of the grammar can solve:
+
+* Quickly locate the problematic grammatical structure of the api version
+* Syntax analysis for the version
+* Prevent the big version upgrade of api syntax from causing backward compatibility
+
+> **[!WARNING]
+> The imported api must be consistent with the syntax version of the main api.
+
+**Grammar definition**
+
+```antlrv4
+'syntax'={checkVersion(p)}STRING
+```
+
+**Grammar description**
+
+syntax: Fixed token, marking the beginning of a syntax structure
+
+checkVersion: Custom go method to detect whether `STRING` is a legal version number. The current detection logic is that STRING must meet the regularity of `(?m)"v[1-9][0-9]"`.
+
+STRING: A string of English double quotes, such as "v1"
+
+An api grammar file can only have 0 or 1 syntax statement. If there is no syntax, the default version is `v1`
+
+**Examples of correct syntax** ✅
+
+eg1: Irregular writing
+
+```api
+syntax="v1"
+```
+
+eg2: Standard writing (recommended)
+
+```api
+syntax = "v2"
+```
+
+**Examples of incorrect syntax** ❌
+
+eg1：
+
+```api
+syntax = "v0"
+```
+
+eg2：
+
+```api
+syntax = v1
+```
+
+eg3：
+
+```api
+syntax = "V1"
+```
+
+## Import syntax block
+
+As the business scale increases, there are more and more structures and services defined in the api.
+All the grammatical descriptions are in one api file. This is a problem, and it will greatly increase the difficulty of reading and maintenance.
+Import The grammar block can help us solve this problem. By splitting the api file, different api files are declared according to certain rules,
+which can reduce the difficulty of reading and maintenance.
+
+> **[!WARNING]
+> Import here does not include package declarations like golang, it is just the introduction of a file path. After the final analysis, all the declarations will be gathered into a spec.Spec.
+> You cannot import multiple identical paths, otherwise it will cause parsing errors.
+
+**Grammar definition**
+
+```antlrv4
+'import' {checkImportValue(p)}STRING
+|'import' '(' ({checkImportValue(p)}STRING)+ ')'
+```
+
+**Grammar description**
+
+import: fixed token, marking the beginning of an import syntax
+
+checkImportValue: Custom go method to detect whether `STRING` is a legal file path. The current detection logic is that STRING must satisfy `(?m)"(?[az AZ 0-9_-])+\. api"` regular.
+
+STRING: A string of English double quotes, such as "foo.api"
+
+**Examples of correct syntax** ✅
+
+eg：
+
+```api
+import "foo.api"
+import "foo/bar.api"
+
+import(
+ "bar.api"
+ "foo/bar/foo.api"
+)
+```
+
+**Examples of incorrect syntax** ❌
+
+eg：
+
+```api
+import foo.api
+import "foo.txt"
+import (
+ bar.api
+ bar.api
+)
+```
+
+## info syntax block
+
+The info grammar block is a grammar body that contains multiple key-value pairs.
+Its function is equivalent to the description of an api service. The parser will map it to spec.Spec for translation into other languages (golang, java, etc.)
+Is the meta element that needs to be carried. If it is just a description of the current api, without considering its translation to other languages,
+you can use simple multi-line comments or java-style documentation comments. For comment descriptions, please refer to the hidden channels below.
+
+> **[!WARNING]
+> Duplicate keys cannot be used, each api file can only have 0 or 1 info syntax block
+
+**Grammar definition**
+
+```antlrv4
+'info' '(' (ID {checkKeyValue(p)}VALUE)+ ')'
+```
+
+**Grammar description**
+
+info: fixed token, marking the beginning of an info syntax block
+
+checkKeyValue: Custom go method to check whether `VALUE` is a legal value.
+
+VALUE: The value corresponding to the key, which can be any character after a single line except'\r','\n',''. For multiple lines, please wrap it with "", but it is strongly recommended that everything be wrapped with ""
+
+**Examples of correct syntax** ✅
+
+eg1：Irregular writing
+
+```api
+info(
+foo: foo value
+bar:"bar value"
+ desc:"long long long long
+long long text"
+)
+```
+
+eg2：Standard writing (recommended)
+
+```api
+info(
+ foo: "foo value"
+ bar: "bar value"
+ desc: "long long long long long long text"
+)
+```
+
+**Examples of incorrect syntax** ❌
+
+eg1：No key-value
+
+```api
+info()
+```
+
+eg2：Does not contain colon
+
+```api
+info(
+ foo value
+)
+```
+
+eg3：key-value does not wrap
+
+```api
+info(foo:"value")
+```
+
+eg4：No key
+
+```api
+info(
+ : "value"
+)
+```
+
+eg5：Illegal key
+
+```api
+info(
+ 12: "value"
+)
+```
+
+eg6：Remove the old version of multi-line syntax
+
+```api
+info(
+ foo: >
+ some text
+ <
+)
+```
+
+## type syntax block
+
+In the api service, we need to use a structure (class) as the carrier of the request body and the response body.
+Therefore, we need to declare some structures to accomplish this. The type syntax block evolved from the type of golang.
+Of course It also retains some of the characteristics of golang type, and the following golang characteristics are used:
+
+* Keep the built-in data types of golang `bool`,`int`,`int8`,`int16`,`int32`,`int64`,`uint`,`uint8`,`uint16`,`uint32`,`uint64`,`uintptr`
+ ,`float32`,`float64`,`complex64`,`complex128`,`string`,`byte`,`rune`,
+* Compatible with golang struct style declaration
+* Keep golang keywords
+
+> **[!WARNING]️
+> * Does not support alias
+> * Does not support `time.Time` data type
+> * Structure name, field name, cannot be a golang keyword
+
+**Grammar definition**
+
+Since it is similar to golang, it will not be explained in detail. Please refer to the typeSpec definition in [ApiParser.g4](https://github.com/zeromicro/go-zero/blob/master/tools/goctl/api/parser/g4/ApiParser.g4) for the specific syntax definition.
+
+**Grammar description**
+
+Refer to golang writing
+
+**Examples of correct syntax** ✅
+
+eg1：Irregular writing
+
+```api
+type Foo struct{
+ Id int `path:"id"` // ①
+ Foo int `json:"foo"`
+}
+
+type Bar struct{
+ // Non-exported field
+ bar int `form:"bar"`
+}
+
+type(
+ // Non-derived structure
+ fooBar struct{
+ FooBar int
+ }
+)
+```
+
+eg2: Standard writing (recommended)
+
+```api
+type Foo{
+ Id int `path:"id"`
+ Foo int `json:"foo"`
+}
+
+type Bar{
+ Bar int `form:"bar"`
+}
+
+type(
+ FooBar{
+ FooBar int
+ }
+)
+```
+
+**Examples of incorrect syntax** ❌
+
+eg
+
+```api
+type Gender int // not support
+
+// Non-struct token
+type Foo structure{
+ CreateTime time.Time // Does not support time.Time
+}
+
+// golang keyword var
+type var{}
+
+type Foo{
+ // golang keyword interface
+ Foo interface
+}
+
+
+type Foo{
+ foo int
+ // The map key must have the built-in data type of golang
+ m map[Bar]string
+}
+```
+
+> [!NOTE] ①
+> The tag definition is the same as the json tag syntax in golang. In addition to the json tag, go-zero also provides some other tags to describe the fields,
+> See the table below for details.
+
+* tag table
+ | tag key | Description | Provider | Effective Coverage | Example | +
| json | Json serialization tag | golang | request、response | json:"fooo" |
+
| path | Routing path, such as/foo/:id | go-zero | request | path:"id" |
+
| form | Mark that the request body is a form (in the POST method) or a query (in the GET method)/search?name=keyword) | go-zero | request | form:"name" |
+
| tag key | Description | Provider | Effective Coverage | Example | +
| optional | Define the current field as an optional parameter | go-zero | request | json:"name,optional" |
+
| options | Define the enumeration value of the current field, separated by a vertical bar | | go-zero | request | json:"gender,options=male" |
+
| default | Define the default value of the current field | go-zero | request | json:"gender,default=male" |
+
| range | Define the value range of the current field | go-zero | request | json:"age,range=[0:120]" |
+
| key | Description | Example | +
| jwt | Declare that all routes under the current service require jwt authentication, and code containing jwt logic will be automatically generated | jwt: Auth |
+
| group | Declare the current service or routing file group | group: login |
+
| middleware | Declare that the current service needs to open the middleware | middleware: AuthMiddleware |
+
| key | Description | Example | +
| handler | Declare a handler | - | +
| Syntax block | Parent Syntax Block | Doc | Comment | +
| syntaxLit | api | ✅ | ✅ | +
| kvLit | infoSpec | ✅ | ✅ | +
| importLit | importSpec | ✅ | ✅ | +
| typeLit | api | ✅ | ❌ | +
| typeLit | typeBlock | ✅ | ❌ | +
| field | typeLit | ✅ | ✅ | +
| key-value | atServer | ✅ | ✅ | +
| atHandler | serviceRoute | ✅ | ✅ | +
| route | serviceRoute | ✅ | ✅ | +
](https://github.com/zeromicro/go-zero)
+[](https://github.com/zeromicro/goctl-intellij/blob/main/LICENSE)
+[](https://github.com/zeromicro/goctl-intellij/releases)
+[](https://github.com/zeromicro/goctl-intellij/actions)
+
+## Introduction
+A plug-in tool that supports go-zero api language structure syntax highlighting, detection, and quick generation of api, rpc, and model.
+
+
+## Idea version requirements
+* IntelliJ 2019.3+ (Ultimate or Community)
+* Goland 2019.3+
+* WebStorm 2019.3+
+* PhpStorm 2019.3+
+* PyCharm 2019.3+
+* RubyMine 2019.3+
+* CLion 2019.3+
+
+## Features
+* api syntax highlighting
+* api syntax and semantic detection
+* struct, route, handler repeated definition detection
+* type jump to the type declaration position
+* Support api, rpc, mode related menu options in the context menu
+* Code formatting (option+command+L)
+* Code hint
+
+## Install
+
+### The way one
+Find the latest zip package in the GitHub release, download it and install it locally. (No need to unzip)
+
+### Thw way two
+In the plugin store, search for `Goctl` to install
+
+
+## Preview
+
+
+## Create a new Api(Proto) file
+In the project area target folder `right click ->New-> New Api(Proto) File ->Empty File/Api(Proto) Template`, as shown in the figure:
+
+
+# Quickly generate api/rpc service
+In the target folder `right click->New->Go Zero -> Api Greet Service/Rpc Greet Service`
+
+
+
+# Api/Rpc/Model Code generation
+
+## The way one(Project Panel)
+
+Corresponding files (api, proto, sql) `right click->New->Go Zero-> Api/Rpc/Model Code`, as shown in the figure:
+
+
+
+## Thw way two（Editor Panel）
+Corresponding files (api, proto, sql) `right click -> Generate-> Api/Rpc/Model Code`
+
+
+# Error message
+
+
+
+# Live Template
+Live Template can speed up our writing of api files. For example, when we enter the `main` keyword in the go file, press the tip and press Enter and insert a piece of template code.
+```go
+func main(){
+
+}
+```
+In other words, you will be more familiar with the picture below. Once upon a time, you still defined the template here.
+
+
+Let’s enter the instructions for using the template in today’s api grammar. Let’s take a look at the effect of the service template.
+
+
+First of all, in the previous picture, take a look at several template effective areas in the api file (psiTree element area)
+
+
+#### Default template and effective scope
+| keyword | psiTree effective scope|description|
+| ---- | ---- | ---- |
+| @doc | ApiService |doc comment template|
+| doc | ApiService |doc comment template|
+| struct | Struct |struct declaration template|
+| info | ApiFile |info block template|
+| type | ApiFile |type group template|
+| handler | ApiService |handler name template|
+| get | ApiService |get method routing template|
+| head | ApiService |head method routing template|
+| post | ApiService |post method routing template|
+| put | ApiService |put method routing template|
+| delete | ApiService |delete method routing template|
+| connect | ApiService |connect method routing template|
+| options | ApiService |options method routing template|
+| trace | ApiService |trace method routing template|
+| service | ApiFile |service service block template|
+| json | Tag、Tag literal |tag template|
+| xml | Tag、Tag literal |tag template|
+| path | Tag、Tag literal |tag template|
+| form | Tag、Tag literal |tag template|
+
+For the corresponding content of each template, you can view the detailed template content in `Goland(mac Os)->Preference->Editor->Live Templates-> Api|Api Tags`, for example, the json tag template content is
+```go
+json:"$FIELD_NAME$"
+```
+
+
+
diff --git a/go-zero.dev/en/join-us.md b/go-zero.dev/en/join-us.md
new file mode 100644
index 00000000..1114556a
--- /dev/null
+++ b/go-zero.dev/en/join-us.md
@@ -0,0 +1,61 @@
+# Join Us
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+
+## Summary
+
+
+[go-zero](https://github.com/zeromicro/go-zero) is based on the [MIT License](https://github.com/zeromicro/go-zero/blob/master/LICENSE) open source projects, if you find bugs, new features, etc. in use, you can participate in the contribution of go-zero. We welcome your active participation and will respond to various questions raised by you as soon as possible. , Pr, etc.
+
+## Contribution form
+* [Pull Request](https://github.com/zeromicro/go-zero/pulls)
+* [Issue](https://github.com/zeromicro/go-zero/issues)
+
+## Contribution notes
+The code in go-zero's Pull request needs to meet certain specifications
+* For naming conventions, please read [naming conventions](naming-spec.md)
+* Mainly English annotations
+* Remark the functional characteristics when pr, the description needs to be clear and concise
+* Increase unit test coverage to 80%+
+
+## Pull Request（pr）
+* Enter [go-zero](https://github.com/zeromicro/go-zero) project, fork a copy of [go-zero](https://github.com/zeromicro/go-zero) Project to its own GitHub repository.
+* Go back to your GitHub homepage and find the `xx/go-zero` project, where xx is your username, such as `anqiansong/go-zero`
+
+ 
+* Clone the code to local
+
+ 
+* Develop code and push to your own GitHub repository
+* Enter the go-zero project in your own GitHub, click on the `[Pull requests]` on the floating layer to enter the Compare page.
+
+ 
+
+* `base repository` choose `tal-tech/go-zero` `base:master`,`head repository` choose `xx/go-zero` `compare:$branch` ，`$branch` is the branch you developed, as shown in the figure:
+
+ 
+
+* Click `[Create pull request]` to realize the pr application
+* To confirm whether the pr submission is successful, enter [Pull requests](https://github.com/zeromicro/go-zero) of [go-zero](https://github.com/zeromicro/go-zero) /pulls) view, there should be a record of your own submission, the name is your branch name during development.
+
+ 
+
+## Issue
+In our community, many partners will actively feedback some problems encountered during the use of go-zero.
+Due to the large number of people in the community, although we will follow the community dynamics in real time,
+the feedback of all questions is random. When our team is still solving a problem raised by a partner, other issues are also fed back,
+which may cause the team to easily ignore it. In order to solve everyone's problems one by one, we strongly recommend that everyone use the issue method.
+Feedback issues, including but not limited to bug, expected new features, etc., we will also reflect in the issue when we implement a certain new feature.
+You can also get the latest trend of go-zero here, and welcome everyone Come and actively participate in the discussion.
+
+### How to issue
+* Click [here](https://github.com/zeromicro/go-zero/issues) to enter go-zero's Issue page or directly visit [https://github.com/zeromicro/go-zero/ issues](https://github.com/zeromicro/go-zero/issues) address
+* Click `[New issue]` in the upper right corner to create a new issue
+* Fill in the issue title and content
+* Click `【Submit new issue】` to submit an issue
+
+
+## Reference
+
+* [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)
\ No newline at end of file
diff --git a/go-zero.dev/en/jwt.md b/go-zero.dev/en/jwt.md
new file mode 100644
index 00000000..1b14e5a5
--- /dev/null
+++ b/go-zero.dev/en/jwt.md
@@ -0,0 +1,240 @@
+# JWT authentication
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## Summary
+> JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and independent method for securely transmitting information as JSON objects between parties. Since this information is digitally signed, it can be verified and trusted. The JWT can be signed using a secret (using the HMAC algorithm) or using a public/private key pair of RSA or ECDSA.
+
+## When should you use JSON Web Tokens?
+* Authorization: This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign On is a feature that widely uses JWT nowadays, because of its small overhead and its ability to be easily used across different domains.
+
+* Information exchange: JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be signed—for example, using public/private key pairs—you can be sure the senders are who they say they are. Additionally, as the signature is calculated using the header and the payload, you can also verify that the content hasn't been tampered with.
+
+## Why should we use JSON Web Tokens?
+As JSON is less verbose than XML, when it is encoded its size is also smaller, making JWT more compact than SAML. This makes JWT a good choice to be passed in HTML and HTTP environments.
+
+Security-wise, SWT can only be symmetrically signed by a shared secret using the HMAC algorithm. However, JWT and SAML tokens can use a public/private key pair in the form of a X.509 certificate for signing. Signing XML with XML Digital Signature without introducing obscure security holes is very difficult when compared to the simplicity of signing JSON.
+
+JSON parsers are common in most programming languages because they map directly to objects. Conversely, XML doesn't have a natural document-to-object mapping. This makes it easier to work with JWT than SAML assertions.
+
+Regarding usage, JWT is used at Internet scale. This highlights the ease of client-side processing of the JSON Web token on multiple platforms, especially mobile.
+
+> [!TIP]
+> All the above content quote from [jwt.io](https://jwt.io/introduction)
+
+## How to use jwt in go-zero
+Jwt authentication is generally used at the api layer. In this demonstration project, we generate jwt token when user api logs in, and verify the user jwt token when searching api for books.
+
+### user api generates jwt token
+Following the content of the [Business Coding](business-coding.md) chapter, we perfect the `getJwtToken` method left over from the previous section, that is, generate the jwt token logic
+
+#### Add configuration definition and yaml configuration items
+```shell
+$ vim service/user/cmd/api/internal/config/config.go
+```
+```go
+type Config struct {
+ rest.RestConf
+ Mysql struct{
+ DataSource string
+ }
+ CacheRedis cache.CacheConf
+ Auth struct {
+ AccessSecret string
+ AccessExpire int64
+ }
+}
+```
+```shell
+$ vim service/user/cmd/api/etc/user-api.yaml
+```
+```yaml
+Name: user-api
+Host: 0.0.0.0
+Port: 8888
+Mysql:
+ DataSource: $user:$password@tcp($url)/$db?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+CacheRedis:
+ - Host: $host
+ Pass: $pass
+ Type: node
+Auth:
+ AccessSecret: $AccessSecret
+ AccessExpire: $AccessExpire
+```
+
+> [!TIP]
+> $AccessSecret: The easiest way to generate the key of the jwt token is to use an uuid value.
+>
+> $AccessExpire: Jwt token validity period, unit: second
+>
+> For more configuration information, please refer to [API Configuration](api-config.md)
+
+```shell
+$ vim service/user/cmd/api/internal/logic/loginlogic.go
+```
+
+```go
+func (l *LoginLogic) getJwtToken(secretKey string, iat, seconds, userId int64) (string, error) {
+ claims := make(jwt.MapClaims)
+ claims["exp"] = iat + seconds
+ claims["iat"] = iat
+ claims["userId"] = userId
+ token := jwt.New(jwt.SigningMethodHS256)
+ token.Claims = claims
+ return token.SignedString([]byte(secretKey))
+}
+```
+
+### search.api uses jwt token authentication
+#### Write search.api file
+```shell
+$ vim service/search/cmd/api/search.api
+```
+```text
+type (
+ SearchReq {
+ Name string `form:"name"`
+ }
+
+ SearchReply {
+ Name string `json:"name"`
+ Count int `json:"count"`
+ }
+)
+
+@server(
+ jwt: Auth
+)
+service search-api {
+ @handler search
+ get /search/do (SearchReq) returns (SearchReply)
+}
+
+service search-api {
+ @handler ping
+ get /search/ping
+}
+```
+
+> [!TIP]
+> `jwt: Auth`: Enable jwt authentication
+>
+> If the routing requires JWT authentication, you need to declare this syntax flag above the service, such as `/search/do` above
+>
+> Routes that do not require jwt authentication do not need to be declared, such as `/search/ping` above
+>
+> For more grammar, please read [API IDL](api-grammar.md)
+
+
+#### Generate code
+As described above, there are three ways to generate code, so I won’t go into details here.
+
+
+#### Add yaml configuration items
+```shell
+$ vim service/search/cmd/api/etc/search-api.yaml
+```
+```yaml
+Name: search-api
+Host: 0.0.0.0
+Port: 8889
+Auth:
+ AccessSecret: $AccessSecret
+ AccessExpire: $AccessExpire
+
+```
+
+> [!TIP]
+> $AccessSecret: This value must be consistent with the one declared in the user api.
+>
+> $AccessExpire: Valid period
+>
+> Modify the port here to avoid conflicts with user api port 8888
+
+### Verify jwt token
+* Start user api service, and login
+ ```shell
+ $ cd service/user/cmd/api
+ $ go run user.go -f etc/user-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+ ```shell
+ $ curl -i -X POST \
+ http://127.0.0.1:8888/user/login \
+ -H 'content-type: application/json' \
+ -d '{
+ "username":"666",
+ "password":"123456"
+ }'
+ ```
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Mon, 08 Feb 2021 10:37:54 GMT
+ Content-Length: 251
+
+ {"id":1,"name":"xiaoming","gender":"male","accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NjcwNzQsImlhdCI6MTYxMjc4MDY3NCwidXNlcklkIjoxfQ.JKa83g9BlEW84IiCXFGwP2aSd0xF3tMnxrOzVebbt80","accessExpire":1612867074,"refreshAfter":1612823874}
+ ```
+* Start the search api service, call `/search/do` to verify whether the jwt authentication is passed
+ ```shell
+ $ go run search.go -f etc/search-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8889...
+ ```
+ Let’s not pass the jwt token and see the result:
+ ```shell
+ $ curl -i -X GET \
+ 'http://127.0.0.1:8889/search/do?name=%E8%A5%BF%E6%B8%B8%E8%AE%B0'
+ ```
+ ```text
+ HTTP/1.1 401 Unauthorized
+ Date: Mon, 08 Feb 2021 10:41:57 GMT
+ Content-Length: 0
+ ```
+ Obviously, the jwt authentication failed, and the statusCode of 401 is returned. Next, let's take a jwt token (that is, the `accessToken` returned by the user login)
+ ```shell
+ $ curl -i -X GET \
+ 'http://127.0.0.1:8889/search/do?name=%E8%A5%BF%E6%B8%B8%E8%AE%B0' \
+ -H 'authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTI4NjcwNzQsImlhdCI6MTYxMjc4MDY3NCwidXNlcklkIjoxfQ.JKa83g9BlEW84IiCXFGwP2aSd0xF3tMnxrOzVebbt80'
+ ```
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Mon, 08 Feb 2021 10:44:45 GMT
+ Content-Length: 21
+
+ {"name":"","count":0}
+ ```
+
+ > [!TIP]
+ > Service startup error, please check [Error](error.md)
+
+
+At this point, the demonstration of jwt from generation to use is complete. The authentication of jwt token is already encapsulated in go-zero. You only need to simply declare it when defining the service in the api file.
+
+### Get the information carried in the jwt token
+After go-zero is parsed from the jwt token, the kv passed in when the user generates the token will be placed in the Context of http.Request intact, so we can get the value you want through the Context.
+
+```shell
+$ vim /service/search/cmd/api/internal/logic/searchlogic.go
+```
+Add a log to output the userId parsed from jwt.
+```go
+func (l *SearchLogic) Search(req types.SearchReq) (*types.SearchReply, error) {
+ logx.Infof("userId: %v",l.ctx.Value("userId"))// 这里的key和生成jwt token时传入的key一致
+ return &types.SearchReply{}, nil
+}
+```
+Output
+```text
+{"@timestamp":"2021-02-09T10:29:09.399+08","level":"info","content":"userId: 1"}
+```
+
+# Guess you wants
+* [JWT](https://jwt.io/)
+* [API Configuration](api-config.md)
+* [API IDL](api-grammar.md)
diff --git a/go-zero.dev/en/learning-resource.md b/go-zero.dev/en/learning-resource.md
new file mode 100644
index 00000000..c96e62f2
--- /dev/null
+++ b/go-zero.dev/en/learning-resource.md
@@ -0,0 +1,8 @@
+# Learning Resources
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+The latest learning resource channel of go-zero will be updated from time to time. Currently, the channels included are:
+* [Wechat](wechat.md)
+* [Night](goreading.md)
+* [OpenTalk](gotalk.md)
\ No newline at end of file
diff --git a/go-zero.dev/en/log-collection.md b/go-zero.dev/en/log-collection.md
new file mode 100644
index 00000000..ee819092
--- /dev/null
+++ b/go-zero.dev/en/log-collection.md
@@ -0,0 +1,144 @@
+# Log Collection
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+In order to ensure the stable operation of the business and predict the unhealthy risks of the service, the collection of logs can help us observe the current health of the service.
+In traditional business development, when there are not many machine deployments, we usually log in directly to the server to view and debug logs. However, as the business increases, services continue to be split.
+
+The maintenance cost of the service will also become more and more complicated. In a distributed system, there are more server machines, and the service is distributed on different servers. When problems are encountered,
+We can't use traditional methods to log in to the server for log investigation and debugging. The complexity can be imagined.
+
+
+
+> [!TIP]
+> If it is a simple single service system, or the service is too small, it is not recommended to use it directly, otherwise it will be counterproductive.
+
+## Prepare
+* kafka
+* elasticsearch
+* kibana
+* filebeat、Log-Pilot（k8s）
+* go-stash
+
+## Filebeat
+```shell
+$ vim xx/filebeat.yaml
+```
+
+```yaml
+filebeat.inputs:
+- type: log
+ enabled: true
+ # Turn on json parsing
+ json.keys_under_root: true
+ json.add_error_key: true
+ # Log file path
+ paths:
+ - /var/log/order/*.log
+
+setup.template.settings:
+ index.number_of_shards: 1
+
+# Define kafka topic field
+fields:
+ log_topic: log-collection
+
+# Export to kafka
+output.kafka:
+ hosts: ["127.0.0.1:9092"]
+ topic: '%{[fields.log_topic]}'
+ partition.round_robin:
+ reachable_only: false
+ required_acks: 1
+ keep_alive: 10s
+
+# ================================= Processors =================================
+processors:
+ - decode_json_fields:
+ fields: ['@timestamp','level','content','trace','span','duration']
+ target: ""
+```
+
+> [!TIP]
+> xx is the path where filebeat.yaml is located
+
+## go-stash configuration
+* Create a new `config.yaml` file
+* Add configuration content
+
+```shell
+$ vim config.yaml
+```
+
+```yaml
+Clusters:
+- Input:
+ Kafka:
+ Name: go-stash
+ Log:
+ Mode: file
+ Brokers:
+ - "127.0.0.1:9092"
+ Topics:
+ - log-collection
+ Group: stash
+ Conns: 3
+ Consumers: 10
+ Processors: 60
+ MinBytes: 1048576
+ MaxBytes: 10485760
+ Offset: first
+ Filters:
+ - Action: drop
+ Conditions:
+ - Key: status
+ Value: "503"
+ Type: contains
+ - Key: type
+ Value: "app"
+ Type: match
+ Op: and
+ - Action: remove_field
+ Fields:
+ - source
+ - _score
+ - "@metadata"
+ - agent
+ - ecs
+ - input
+ - log
+ - fields
+ Output:
+ ElasticSearch:
+ Hosts:
+ - "http://127.0.0.1:9200"
+ Index: "go-stash-{{yyyy.MM.dd}}"
+ MaxChunkBytes: 5242880
+ GracePeriod: 10s
+ Compress: false
+ TimeZone: UTC
+```
+
+## Start services (start in order)
+* Start kafka
+* Start elasticsearch
+* Start kibana
+* Start go-stash
+* Start filebeat
+* Start the order-api service and its dependent services (order-api service in the go-zero-demo project)
+
+## Visit kibana
+Enter 127.0.0.1:5601
+
+
+> [!TIP]
+> Here we only demonstrate the logs generated by logx in the collection service, and log collection in nginx is the same.
+
+
+# Reference
+* [kafka](http://kafka.apache.org/)
+* [elasticsearch](https://www.elastic.co/cn/elasticsearch/)
+* [kibana](https://www.elastic.co/cn/kibana)
+* [filebeat](https://www.elastic.co/cn/beats/filebeat)
+* [go-stash](https://github.com/tal-tech/go-stash)
+* [filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/index.html)
diff --git a/go-zero.dev/en/logx.md b/go-zero.dev/en/logx.md
new file mode 100644
index 00000000..6b8d7ad4
--- /dev/null
+++ b/go-zero.dev/en/logx.md
@@ -0,0 +1,186 @@
+# logx
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## Example
+
+```go
+var c logx.LogConf
+// Initialize the configuration from the yaml file
+conf.MustLoad("config.yaml", &c)
+
+// logx is initialized according to the configuration
+logx.MustSetup(c)
+
+logx.Info("This is info!")
+logx.Infof("This is %s!", "info")
+
+logx.Error("This is error!")
+logx.Errorf("this is %s!", "error")
+
+logx.Close()
+```
+
+## Initialization
+logx has many configurable items, you can refer to the definition in logx.LogConf. Currently available
+
+```go
+logx.MustSetUp(c)
+```
+Perform the initial configuration. If the initial configuration is not performed, all the configurations will use the default configuration.
+
+## Level
+The print log levels supported by logx are:
+- info
+- error
+- server
+- fatal
+- slow
+- stat
+
+You can use the corresponding method to print out the log of the corresponding level.
+At the same time, in order to facilitate debugging and online use, the log printing level can be dynamically adjusted. The level can be set through **logx.SetLevel(uint32)** or through configuration initialization. The currently supported parameters are:
+
+```go
+const (
+ // Print all levels of logs
+ InfoLevel = iotas
+ // Print errors, slows, stacks logs
+ ErrorLevel
+ // Only print server level logs
+ SevereLevel
+)
+```
+
+## Log mode
+At present, the log printing mode is mainly divided into two types, one is file output, and the other is console output. The recommended way, when using k8s, docker and other deployment methods, you can output the log to the console, use the log collector to collect and import it to es for log analysis. If it is a direct deployment method, the file output method can be used, and logx will automatically create log files corresponding to 5 corresponding levels in the specified file directory to save the logs.
+
+```bash
+.
+├── access.log
+├── error.log
+├── severe.log
+├── slow.log
+└── stat.log
+```
+
+At the same time, the file will be divided according to the natural day. When the specified number of days is exceeded, the log file will be automatically deleted, packaged and other operations.
+
+## Disable log
+If you don't need log printing, you can use **logx.Close()** to close the log output. Note that when log output is disabled, it cannot be opened again. For details, please refer to the implementation of **logx.RotateLogger** and **logx.DailyRotateRule**.
+
+## Close log
+Because logx uses asynchronous log output, if the log is not closed normally, some logs may be lost. The log output must be turned off where the program exits:
+```go
+logx.Close()
+```
+Log configuration and shutdown related operations have already been done in most places such as rest and zrpc in the framework, so users don't need to care.
+At the same time, note that when the log output is turned off, the log cannot be printed again.
+
+Recommended writing:
+```go
+import "github.com/tal-tech/go-zero/core/proc"
+
+// grace close log
+proc.AddShutdownListener(func() {
+ logx.Close()
+})
+```
+
+## Duration
+When we print the log, we may need to print the time-consuming situation, we can use **logx.WithDuration(time.Duration)**, refer to the following example:
+
+```go
+startTime := timex.Now()
+// Database query
+rows, err := conn.Query(q, args...)
+duration := timex.Since(startTime)
+if duration > slowThreshold {
+ logx.WithDuration(duration).Slowf("[SQL] query: slowcall - %s", stmt)
+} else {
+ logx.WithDuration(duration).Infof("sql query: %s", stmt)
+}
+```
+
+
+Will output the following format:
+
+```json
+{"@timestamp":"2020-09-12T01:22:55.552+08","level":"info","duration":"3.0ms","content":"sql query:..."}
+{"@timestamp":"2020-09-12T01:22:55.552+08","level":"slow","duration":"500ms","content":"[SQL] query: slowcall - ..."}
+```
+
+In this way, it is easy to collect statistics about slow sql related information.
+
+## TraceLog
+tracingEntry is customized for link tracing log output. You can print the traceId and spanId information in the context. With our **rest** and **zrpc**, it is easy to complete the related printing of the link log. The example is as follows:
+
+```go
+logx.WithContext(context.Context).Info("This is info!")
+```
+
+
+## SysLog
+
+Some applications may use system log for log printing. Logx uses the same encapsulation method, which makes it easy to collect log-related logs into logx.
+
+```go
+logx.CollectSysLog()
+```
+
+
+
+
+# Log configuration related
+**LogConf** Define the basic configuration required for the logging system
+
+The complete definition is as follows:
+
+```go
+type LogConf struct {
+ ServiceName string `json:",optional"`
+ Mode string `json:",default=console,options=console|file|volume"`
+ Path string `json:",default=logs"`
+ Level string `json:",default=info,options=info|error|severe"`
+ Compress bool `json:",optional"`
+ KeepDays int `json:",optional"`
+ StackCooldownMillis int `json:",default=100"`
+}
+```
+
+
+## Mode
+**Mode** defines the log printing method. The default mode is **console**, which will print to the console.
+
+The currently supported modes are as follows:
+
+- console
+ - Print to the console
+- file
+ - Print to access.log, error.log, stat.log and other files in the specified path
+- volume
+ - In order to print to the storage that the mount comes in in k8s, because multiple pods may overwrite the same file, the volume mode automatically recognizes the pod and writes separate log files according to the pod.
+
+## Path
+**Path** defines the output path of the file log, the default value is **logs**.
+
+## Level
+**Level** defines the log printing level, and the default value is **info**.
+The currently supported levels are as follows:
+
+- info
+- error
+- severe
+
+
+
+## Compress
+**Compress** defines whether the log needs to be compressed, the default value is **false**. When Mode is file mode, the file will finally be packaged and compressed into a .gz file.
+
+
+## KeepDays
+**KeepDays** defines the maximum number of days to keep logs. The default value is 0, which means that old logs will not be deleted. When Mode is file mode, if the maximum retention days are exceeded, the old log files will be deleted.
+
+
+## StackCooldownMillis
+**StackCooldownMillis** defines the log output interval, the default is 100 milliseconds.
diff --git a/go-zero.dev/en/micro-service.md b/go-zero.dev/en/micro-service.md
new file mode 100644
index 00000000..e24a8186
--- /dev/null
+++ b/go-zero.dev/en/micro-service.md
@@ -0,0 +1,291 @@
+# Microservice
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+In the previous article, we have demonstrated how to quickly create a monolithic service. Next, let’s demonstrate how to quickly create a microservice.
+In this section, the api part is actually the same as the creation logic of the monolithic service, except that there is no communication between services in the monolithic service.
+And the api service in the microservice will have more rpc call configuration.
+
+## Forward
+This section will briefly demonstrate with an `order service` calling `user service`. The demo code only conveys ideas, and some links will not be listed one by one.
+
+## Scenario summary
+Suppose we are developing a mall project, and the developer Xiao Ming is responsible for the development of the user module (user) and the order module (order). Let's split these two modules into two microservices.①
+
+> [!NOTE]
+> ①: The splitting of microservices is also a science, and we will not discuss the details of how to split microservices here.
+
+## Demonstration function goal
+* Order service (order) provides a query interface
+* User service (user) provides a method for order service to obtain user information
+
+## Service design analysis
+According to the scenario summary, we can know that the order is directly facing the user, and the data is accessed through the http protocol, and some basic data of the user needs to be obtained inside the order. Since our service adopts the microservice architecture design,
+Then two services (user, order) must exchange data. The data exchange between services is the communication between services. At this point, it is also a developer’s need to adopt a reasonable communication protocol.
+For consideration, communication can be carried out through http, rpc and other methods. Here we choose rpc to implement communication between services. I believe that I have already made a better scenario description of "What is the role of rpc service?".
+Of course, there is much more than this design analysis before a service is developed, and we will not describe it in detail here. From the above, we need:
+* user rpc
+* order api
+
+two services to initially implement this small demo.
+
+## Create mall project
+```shell
+$ cd ~/go-zero-demo
+$ mkdir mall && cd mall
+```
+
+## Create user rpc service
+
+* new user rpc
+ ```shell
+ $ cd ~/go-zero-demo/mall
+ $ mkdir -p user/rpc&&cd user/rpc
+ ```
+
+* Add `user.proto` file, add `getUser` method
+
+ ```shell
+ $ vim ~/go-zero-demo/mall/user/user.proto
+ ```
+
+ ```protobuf
+ syntax = "proto3";
+
+ package user;
+
+ option go_package = "user";
+
+ message IdRequest {
+ string id = 1;
+ }
+
+ message UserResponse {
+ string id = 1;
+ string name = 2;
+ string gender = 3;
+ }
+
+ service User {
+ rpc getUser(IdRequest) returns(UserResponse);
+ }
+ ```
+* Generate code
+
+ ```shell
+ $ cd ~/go-zero-demo/mall/user/rpc
+ $ goctl rpc proto -src user.proto -dir .
+ [goclt version <=1.2.1] protoc -I=/Users/xx/mall/user user.proto --goctl_out=plugins=grpc:/Users/xx/mall/user/user
+ [goctl version > 1.2.1] protoc -I=/Users/xx/mall/user user.proto --go_out=plugins=grpc:/Users/xx/mall/user/user
+ Done.
+ ```
+
+> [!TIPS]
+> If the installed version of `protoc-gen-go` is larger than 1.4.0, it is recommended to add `go_package` to the proto file
+
+
+* Fill in business logic
+
+ ```shell
+ $ vim internal/logic/getuserlogic.go
+ ```
+ ```go
+ package logic
+
+ import (
+ "context"
+
+ "go-zero-demo/mall/user/internal/svc"
+ "go-zero-demo/mall/user/user"
+
+ "github.com/tal-tech/go-zero/core/logx"
+ )
+
+ type GetUserLogic struct {
+ ctx context.Context
+ svcCtx *svc.ServiceContext
+ logx.Logger
+ }
+
+ func NewGetUserLogic(ctx context.Context, svcCtx *svc.ServiceContext) *GetUserLogic {
+ return &GetUserLogic{
+ ctx: ctx,
+ svcCtx: svcCtx,
+ Logger: logx.WithContext(ctx),
+ }
+ }
+
+ func (l *GetUserLogic) GetUser(in *user.IdRequest) (*user.UserResponse, error) {
+ return &user.UserResponse{
+ Id: "1",
+ Name: "test",
+ }, nil
+ }
+ ```
+
+## Create order api service
+* Create an `order api` service
+
+ ```shell
+ $ cd ~/go-zero-demo/mall
+ $ mkdir -p order/api&&cd order/api
+ ```
+
+* Add api file
+ ```shell
+ $ vim order.api
+ ```
+ ```go
+ type(
+ OrderReq {
+ Id string `path:"id"`
+ }
+
+ OrderReply {
+ Id string `json:"id"`
+ Name string `json:"name"`
+ }
+ )
+ service order {
+ @handler getOrder
+ get /api/order/get/:id (OrderReq) returns (OrderReply)
+ }
+ ```
+* Generate `order` service
+ ```shell
+ $ goctl api go -api order.api -dir .
+ Done.
+ ```
+* Add user rpc configuration
+
+ ```shell
+ $ vim internal/config/config.go
+ ```
+ ```go
+ package config
+
+ import "github.com/tal-tech/go-zero/rest"
+ import "github.com/tal-tech/go-zero/zrpc"
+
+ type Config struct {
+ rest.RestConf
+ UserRpc zrpc.RpcClientConf
+ }
+ ```
+* Add yaml configuration
+
+ ```shell
+ $ vim etc/order.yaml
+ ```
+ ```yaml
+ Name: order
+ Host: 0.0.0.0
+ Port: 8888
+ UserRpc:
+ Etcd:
+ Hosts:
+ - 127.0.0.1:2379
+ Key: user.rpc
+ ```
+* Improve service dependence
+
+ ```shell
+ $ vim internal/svc/servicecontext.go
+ ```
+ ```go
+ package svc
+
+ import (
+ "go-zero-demo/mall/order/api/internal/config"
+ "go-zero-demo/mall/user/rpc/userclient"
+
+ "github.com/tal-tech/go-zero/zrpc"
+ )
+
+ type ServiceContext struct {
+ Config config.Config
+ UserRpc userclient.User
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ UserRpc: userclient.NewUser(zrpc.MustNewClient(c.UserRpc)),
+ }
+ }
+ ```
+
+* Add order demo logic
+
+ Add business logic to `getorderlogic`
+ ```shell
+ $ vim ~/go-zero-demo/mall/order/api/internal/logic/getorderlogic.go
+ ```
+ ```go
+ user, err := l.svcCtx.UserRpc.GetUser(l.ctx, &userclient.IdRequest{
+ Id: "1",
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ if user.Name != "test" {
+ return nil, errors.New("User does not exist")
+ }
+
+ return &types.OrderReply{
+ Id: req.Id,
+ Name: "test order",
+ }, nil
+ ```
+
+## Start the service and verify
+* Start etcd
+ ```shell
+ $ etcd
+ ```
+* Start user rpc
+ ```shell
+ $ go run user.go -f etc/user.yaml
+ ```
+ ```text
+ Starting rpc server at 127.0.0.1:8080...
+ ```
+
+* Start order api
+ ```shell
+ $ go run order.go -f etc/order.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+* Access order api
+ ```shell
+ curl -i -X GET \
+ http://localhost:8888/api/order/get/1
+ ```
+
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sun, 07 Feb 2021 03:45:05 GMT
+ Content-Length: 30
+
+ {"id":"1","name":"test order"}
+ ```
+
+> [!TIP]
+> The api syntax mentioned in the demo, how to use and install rpc generation, goctl, goctl environment, etc. are not outlined in detail in the quick start. We will have detailed documents to describe in the follow-up. You can also click on the following [Guess you think View] View the corresponding document for quick jump.
+
+# Source code
+[mall source code](https://github.com/zeromicro/go-zero-demo/tree/master/mall)
+
+# Guess you wants
+* [Goctl](goctl.md)
+* [API Directory Structure](api-dir.md)
+* [API IDL](api-grammar.md)
+* [API Configuration](api-config.md)
+* [Middleware](middleware.md)
+* [RPC Directory Structure](rpc-dir.md)
+* [RPC Configuration](rpc-config.md)
+* [RPC Implement & Call](rpc-call.md)
diff --git a/go-zero.dev/en/middleware.md b/go-zero.dev/en/middleware.md
new file mode 100644
index 00000000..f3abea01
--- /dev/null
+++ b/go-zero.dev/en/middleware.md
@@ -0,0 +1,127 @@
+# Middleware
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+In the previous section, we demonstrated how to use jwt authentication. I believe you have mastered the basic use of jwt. In this section, let’s take a look at how to use api service middleware.
+
+## Middleware classification
+In go-zero, middleware can be divided into routing middleware and global middleware. Routing middleware refers to certain specific routes that need to implement middleware logic, which is similar to jwt and does not place the routes under `jwt:xxx` Does not use middleware functions,
+The service scope of global middleware is the entire service.
+
+## Middleware use
+Here we take the `search` service as an example to demonstrate the use of middleware
+
+### Routing middleware
+* Rewrite the `search.api` file and add the `middleware` declaration
+ ```shell
+ $ cd service/search/cmd/api
+ $ vim search.api
+ ```
+ ```text
+ type SearchReq struct {}
+
+ type SearchReply struct {}
+
+ @server(
+ jwt: Auth
+ middleware: Example // Routing middleware declaration
+ )
+ service search-api {
+ @handler search
+ get /search/do (SearchReq) returns (SearchReply)
+ }
+ ```
+* Regenerate the api code
+ ```shell
+ $ goctl api go -api search.api -dir .
+ ```
+ ```text
+ etc/search-api.yaml exists, ignored generation
+ internal/config/config.go exists, ignored generation
+ search.go exists, ignored generation
+ internal/svc/servicecontext.go exists, ignored generation
+ internal/handler/searchhandler.go exists, ignored generation
+ internal/handler/pinghandler.go exists, ignored generation
+ internal/logic/searchlogic.go exists, ignored generation
+ internal/logic/pinglogic.go exists, ignored generation
+ Done.
+ ```
+ After the generation is completed, there will be an additional `middleware` directory under the `internal` directory, which is the middleware file, and the implementation logic of the subsequent middleware is also written here.
+* Improve resource dependency `ServiceContext`
+ ```shell
+ $ vim service/search/cmd/api/internal/svc/servicecontext.go
+ ```
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ Example rest.Middleware
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ Example: middleware.NewExampleMiddleware().Handle,
+ }
+ }
+ ```
+* Write middleware logic
+ Only one line of log is added here, with the content example middle. If the service runs and outputs example middle, it means that the middleware is in use.
+
+ ```shell
+ $ vim service/search/cmd/api/internal/middleware/examplemiddleware.go
+ ```
+ ```go
+ package middleware
+
+ import "net/http"
+
+ type ExampleMiddleware struct {
+ }
+
+ func NewExampleMiddleware() *ExampleMiddleware {
+ return &ExampleMiddleware{}
+ }
+
+ func (m *ExampleMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ // TODO generate middleware implement function, delete after code implementation
+
+ // Passthrough to next handler if need
+ next(w, r)
+ }
+ }
+ ```
+* Start service verification
+ ```text
+ {"@timestamp":"2021-02-09T11:32:57.931+08","level":"info","content":"example middle"}
+ ```
+
+### Global middleware
+call `rest.Server.Use`
+```go
+func main() {
+ flag.Parse()
+
+ var c config.Config
+ conf.MustLoad(*configFile, &c)
+
+ ctx := svc.NewServiceContext(c)
+ server := rest.MustNewServer(c.RestConf)
+ defer server.Stop()
+
+ // Global middleware
+ server.Use(func(next http.HandlerFunc) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ logx.Info("global middleware")
+ next(w, r)
+ }
+ })
+ handler.RegisterHandlers(server, ctx)
+
+ fmt.Printf("Starting server at %s:%d...\n", c.Host, c.Port)
+ server.Start()
+}
+```
+```text
+{"@timestamp":"2021-02-09T11:50:15.388+08","level":"info","content":"global middleware"}
+```
\ No newline at end of file
diff --git a/go-zero.dev/en/model-gen.md b/go-zero.dev/en/model-gen.md
new file mode 100644
index 00000000..0837d399
--- /dev/null
+++ b/go-zero.dev/en/model-gen.md
@@ -0,0 +1,59 @@
+# Model Generation
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+
+First, after downloading the [demo project](https://go-zero.dev/en/resource/book.zip), we will use the user's model to demonstrate the code generation.
+
+## Forward
+Model is a bridge for services to access the persistent data layer. The persistent data of the business often exists in databases such as mysql and mongo. We all know that the operation of a database is nothing more than CURD.
+And these tasks will also take up part of the time for development. I once wrote 40 model files when writing a business. According to the complexity of different business requirements, on average, each model file is almost required.
+10 minutes, for 40 files, 400 minutes of working time, almost a day's workload, and the goctl tool can complete the 400 minutes of work in 10 seconds.
+
+## Prepare
+Enter the demo project `book`, find the` user.sql` file under `user/model`, and execute the table creation in your own database.
+
+## Code generation (with cache)
+### The way one(ddl)
+Enter the `service/user/model` directory and execute the command
+```shell
+$ cd service/user/model
+$ goctl model mysql ddl -src user.sql -dir . -c
+```
+```text
+Done.
+```
+
+### The way two(datasource)
+```shell
+$ goctl model mysql datasource -url="$datasource" -table="user" -c -dir .
+```
+```text
+Done.
+```
+> [!TIP]
+> `$datasource` is the database connection address
+
+### The way three(intellij plugin)
+In Goland, right-click `user.sql`, enter and click `New`->`Go Zero`->`Model Code` to generate it, or open the `user.sql` file,
+Enter the editing area, use the shortcut key `Command+N` (for macOS) or `alt+insert` (for windows), select `Mode Code`.
+
+
+
+> [!TIP]
+> The intellij plug-in generation needs to install the goctl plug-in, see [intellij plugin](intellij.md) for details
+
+## Verify the generated model file
+view tree
+```shell
+$ tree
+```
+```text
+.
+├── user.sql
+├── usermodel.go
+└── vars.go
+```
+
+# Guess you wants
+[Model Commands](goctl-model.md)
diff --git a/go-zero.dev/en/monolithic-service.md b/go-zero.dev/en/monolithic-service.md
new file mode 100644
index 00000000..f3641d20
--- /dev/null
+++ b/go-zero.dev/en/monolithic-service.md
@@ -0,0 +1,94 @@
+# Monolithic Service
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+## Forward
+Since go-zero integrates web/rpc, some friends in the community will ask me whether go-zero is positioned as a microservice framework.
+The answer is no. Although go-zero integrates many functions, you can use any one of them independently, or you can develop a single service.
+
+It is not that every service must adopt the design of the microservice architecture. For this point, you can take a look at the fourth issue of the author (kevin) [OpenTalk](https://www.bilibili.com/video/BV1Jy4y127Xu) , Which has a detailed explanation on this.
+
+## Create greet service
+```shell
+$ cd ~/go-zero-demo
+$ goctl api new greet
+Done.
+```
+
+Take a look at the structure of the `greet` service
+```shell
+$ cd greet
+$ tree
+```
+```text
+.
+├── etc
+│ └── greet-api.yaml
+├── go.mod
+├── greet.api
+├── greet.go
+└── internal
+ ├── config
+ │ └── config.go
+ ├── handler
+ │ ├── greethandler.go
+ │ └── routes.go
+ ├── logic
+ │ └── greetlogic.go
+ ├── svc
+ │ └── servicecontext.go
+ └── types
+ └── types.go
+```
+It can be observed from the above directory structure that although the `greet` service is small, it has "all internal organs". Next, we can write business code in `greetlogic.go`.
+
+## Write logic
+```shell
+$ vim ~/go-zero-demo/greet/internal/logic/greetlogic.go
+```
+```go
+func (l *GreetLogic) Greet(req types.Request) (*types.Response, error) {
+ return &types.Response{
+ Message: "Hello go-zero",
+ }, nil
+}
+```
+
+## Start and access the service
+
+* Start service
+ ```shell
+ $ cd ~/go-zer-demo/greet
+ $ go run greet.go -f etc/greet-api.yaml
+ ```
+ ```text
+ Starting server at 0.0.0.0:8888...
+ ```
+
+* Access service
+ ```shell
+ $ curl -i -X GET \
+ http://localhost:8888/from/you
+ ```
+
+ ```text
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sun, 07 Feb 2021 04:31:25 GMT
+ Content-Length: 27
+
+ {"message":"Hello go-zero"}
+ ```
+
+# Source code
+[greet source code](https://github.com/zeromicro/go-zero-demo/tree/master/greet)
+
+# Guess you wants
+* [Goctl](goctl.md)
+* [API Directory Structure](api-dir.md)
+* [API IDL](api-grammar.md)
+* [API Configuration](api-config.md)
+* [Middleware](middleware.md)
+
+
+
diff --git a/go-zero.dev/en/mysql.md b/go-zero.dev/en/mysql.md
new file mode 100644
index 00000000..1a41b363
--- /dev/null
+++ b/go-zero.dev/en/mysql.md
@@ -0,0 +1,182 @@
+# Mysql
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+`go-zero` provides easier operation of `mysql` API.
+
+> [!TIP]
+> But `stores/mysql` positioning is not an `orm` framework. If you need to generate `model` layer code through `sql/scheme` -> `model/struct` reverse engineering, developers can use [goctl model](https://go-zero.dev/cn/goctl-model.html), this is an excellent feature.
+
+
+
+## Features
+
+- Provides a more developer-friendly API compared to native
+- Complete the automatic assignment of `queryField -> struct`
+- Insert "bulkinserter" in batches
+- Comes with fuse
+- API has been continuously tested by several services
+- Provide `partial assignment` feature, do not force strict assignment of `struct`
+
+
+
+## Connection
+Let's use an example to briefly explain how to create a `mysql` connected model:
+```go
+// 1. Quickly connect to a mysql
+// datasource: mysql dsn
+heraMysql := sqlx.NewMysql(datasource)
+
+// 2. Call in the `servicecontext`, understand the logic layer call of the model upper layer
+model.NewMysqlModel(heraMysql, tablename),
+
+// 3. model layer mysql operation
+func NewMysqlModel(conn sqlx.SqlConn, table string) *MysqlModel {
+ defer func() {
+ recover()
+ }()
+ // 4. Create a batch insert [mysql executor]
+ // conn: mysql connection; insertsql: mysql insert sql
+ bulkInserter , err := sqlx.NewBulkInserter(conn, insertsql)
+ if err != nil {
+ logx.Error("Init bulkInsert Faild")
+ panic("Init bulkInsert Faild")
+ return nil
+ }
+ return &MysqlModel{conn: conn, table: table, Bulk: bulkInserter}
+}
+```
+
+
+## CRUD
+
+Prepare an `User model`
+```go
+var userBuilderQueryRows = strings.Join(builderx.FieldNames(&User{}), ",")
+
+type User struct {
+ Avatar string `db:"avatar"`
+ UserName string `db:"user_name"`
+ Sex int `db:"sex"`
+ MobilePhone string `db:"mobile_phone"`
+}
+```
+Among them, `userBuilderQueryRows`: `go-zero` provides `struct -> [field...]` conversion. Developers can use this as a template directly.
+### insert
+```go
+// An actual insert model layer operation
+func (um *UserModel) Insert(user *User) (int64, error) {
+ const insertsql = `insert into `+um.table+` (`+userBuilderQueryRows+`) values(?, ?, ?)`
+ // insert op
+ res, err := um.conn.Exec(insertsql, user.Avatar, user.UserName, user.Sex, user.MobilePhone)
+ if err != nil {
+ logx.Errorf("insert User Position Model Model err, err=%v", err)
+ return -1, err
+ }
+ id, err := res.LastInsertId()
+ if err != nil {
+ logx.Errorf("insert User Model to Id parse id err,err=%v", err)
+ return -1, err
+ }
+ return id, nil
+}
+```
+
+- Splicing `insertsql`
+- Pass in `insertsql` and the `struct field` corresponding to the placeholder -> `con.Exex(insertsql, field...)`
+
+
+> [!WARNING]
+> `conn.Exec(sql, args...)`: `args...` needs to correspond to the placeholder in `sql`. Otherwise, there will be problems with assignment exceptions.
+
+
+`go-zero` unified and abstracted operations involving `mysql` modification as `Exec()`. So the `insert/update/delete` operations are essentially the same. For the remaining two operations, the developer can try the above `insert` process.
+
+
+### query
+
+
+You only need to pass in the `querysql` and `model` structure, and you can get the assigned `model`. No need for developers to manually assign values.
+```go
+func (um *UserModel) FindOne(uid int64) (*User, error) {
+ var user User
+ const querysql = `select `+userBuilderQueryRows+` from `+um.table+` where id=? limit 1`
+ err := um.conn.QueryRow(&user, querysql, uid)
+ if err != nil {
+ logx.Errorf("userId.findOne error, id=%d, err=%s", uid, err.Error())
+ if err == sqlx.ErrNotFound {
+ return nil, ErrNotFound
+ }
+ return nil, err
+ }
+ return &user, nil
+}
+```
+
+- Declare `model struct`, splicing `querysql`
+- `conn.QueryRow(&model, querysql, args...)`: `args...` corresponds to the placeholder in `querysql`.
+
+
+
+> [!WARNING]
+> The first parameter in `QueryRow()` needs to be passed in `Ptr` "The bottom layer needs to be reflected to assign a value to `struct`"
+
+The above is to query one record, if you need to query multiple records, you can use `conn.QueryRows()`
+```go
+func (um *UserModel) FindOne(sex int) ([]*User, error) {
+ users := make([]*User, 0)
+ const querysql = `select `+userBuilderQueryRows+` from `+um.table+` where sex=?`
+ err := um.conn.QueryRows(&users, querysql, sex)
+ if err != nil {
+ logx.Errorf("usersSex.findOne error, sex=%d, err=%s", uid, err.Error())
+ if err == sqlx.ErrNotFound {
+ return nil, ErrNotFound
+ }
+ return nil, err
+ }
+ return users, nil
+}
+```
+The difference from `QueryRow()` is: `model` needs to be set to `Slice`, because it is to query multiple rows, and multiple `model`s need to be assigned. But at the same time you need to pay attention to ️: the first parameter needs to be passed in `Ptr`
+
+### querypartial
+
+
+In terms of use, it is no different from the above-mentioned `QueryRow()`, "this reflects the highly abstract design of `go-zero`."
+
+
+the difference:
+
+- `QueryRow()`: `len(querysql fields) == len(struct)`, and one-to-one correspondence
+- `QueryRowPartial()` ：`len(querysql fields) <= len(struct)`
+
+
+
+numA: Number of database fields; numB: the number of defined `struct` attributes.
+If `numA 
+
+* In this tutorial, I only use one rpc service, transform, to demonstrate. It’s not telling that one API Gateway only can call one RPC service, it’s only for simplicity here.
+* In production, we should try best to isolate the data belongs to services, that means each service should only use its own database.
+
+## 3. goctl generated code overview
+
+All modules with green background are generated, and will be enabled when necessary. The modules with red background are handwritten code, which is typically business logic code.
+
+* API Gateway
+
+ 
+
+* RPC
+
+ 
+
+* model
+
+ 
+
+And now, let’s walk through the complete flow of quickly create a microservice with go-zero.
+
+## 4. Get started
+
+* install etcd, mysql, redis
+
+* install protoc-gen-go
+
+ ```
+ go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2
+ ```
+
+* install goctl
+
+ ```shell
+ GO111MODULE=on go get -u github.com/tal-tech/go-zero/tools/goctl
+ ```
+
+* create the working dir `shorturl` and `shorturl/api`
+
+* in `shorturl` dir, execute `go mod init shorturl` to initialize `go.mod`
+
+## 5. Write code for API Gateway
+
+* use goctl to generate `api/shorturl.api`
+
+ ```shell
+ goctl api -o shorturl.api
+ ```
+
+ for simplicity, the leading `info` block is removed, and the code looks like:
+
+ ```go
+ type (
+ expandReq {
+ shorten string `form:"shorten"`
+ }
+
+ expandResp {
+ url string `json:"url"`
+ }
+ )
+
+ type (
+ shortenReq {
+ url string `form:"url"`
+ }
+
+ shortenResp {
+ shorten string `json:"shorten"`
+ }
+ )
+
+ service shorturl-api {
+ @server(
+ handler: ShortenHandler
+ )
+ get /shorten(shortenReq) returns(shortenResp)
+
+ @server(
+ handler: ExpandHandler
+ )
+ get /expand(expandReq) returns(expandResp)
+ }
+ ```
+
+ the usage of `type` keyword is the same as that in go, service is used to define get/post/head/delete api requests, described below:
+
+ * `service shorturl-api {` defines the service name
+ * `@server` defines the properties that used in server side
+ * `handler` defines the handler name
+ * `get /shorten(shortenReq) returns(shortenResp)` defines this is a GET request, the request parameters, and the response parameters
+
+* generate the code for API Gateway by using goctl
+
+ ```shell
+ goctl api go -api shorturl.api -dir .
+ ```
+
+ the generated file structure looks like:
+
+ ```Plain Text
+ .
+ ├── api
+ │ ├── etc
+ │ │ └── shorturl-api.yaml // configuration file
+ │ ├── internal
+ │ │ ├── config
+ │ │ │ └── config.go // configuration definition
+ │ │ ├── handler
+ │ │ │ ├── expandhandler.go // implements expandHandler
+ │ │ │ ├── routes.go // routes definition
+ │ │ │ └── shortenhandler.go // implements shortenHandler
+ │ │ ├── logic
+ │ │ │ ├── expandlogic.go // implements ExpandLogic
+ │ │ │ └── shortenlogic.go // implements ShortenLogic
+ │ │ ├── svc
+ │ │ │ └── servicecontext.go // defines ServiceContext
+ │ │ └── types
+ │ │ └── types.go // defines request/response
+ │ ├── shorturl.api
+ │ └── shorturl.go // main entrance
+ ├── go.mod
+ └── go.sum
+ ```
+
+* start API Gateway service, listens on port 8888 by default
+
+ ```shell
+ go run shorturl.go -f etc/shorturl-api.yaml
+ ```
+
+* test API Gateway service
+
+ ```shell
+ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn"
+ ```
+
+ response like:
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Thu, 27 Aug 2020 14:31:39 GMT
+ Content-Length: 15
+
+ {"shortUrl":""}
+ ```
+
+ You can see that the API Gateway service did nothing except returned a zero value. And let’s implement the business logic in rpc service.
+
+* you can modify `internal/svc/servicecontext.go` to pass dependencies if needed
+
+* implement logic in package `internal/logic`
+
+* you can use goctl to generate code for clients base on the .api file
+
+* till now, the client engineer can work with the api, don’t need to wait for the implementation of server side
+
+## 6. Write code for transform rpc service
+
+- under directory `shorturl` create dir `rpc`
+
+* under directory `rpc/transform` create `transform.proto` file
+
+ ```shell
+ goctl rpc template -o transform.proto
+ ```
+
+ edit the file and make the code looks like:
+
+ ```protobuf
+ syntax = "proto3";
+
+ package transform;
+
+ message expandReq {
+ string shorten = 1;
+ }
+
+ message expandResp {
+ string url = 1;
+ }
+
+ message shortenReq {
+ string url = 1;
+ }
+
+ message shortenResp {
+ string shorten = 1;
+ }
+
+ service transformer {
+ rpc expand(expandReq) returns(expandResp);
+ rpc shorten(shortenReq) returns(shortenResp);
+ }
+ ```
+
+* use goctl to generate the rpc code, execute the following command in `rpc/transofrm`
+
+ ```shell
+ goctl rpc proto -src transform.proto -dir .
+ ```
+
+ the generated file structure looks like:
+
+ ```Plain Text
+ rpc/transform
+ ├── etc
+ │ └── transform.yaml // configuration file
+ ├── internal
+ │ ├── config
+ │ │ └── config.go // configuration definition
+ │ ├── logic
+ │ │ ├── expandlogic.go // implements expand logic
+ │ │ └── shortenlogic.go // implements shorten logic
+ │ ├── server
+ │ │ └── transformerserver.go // rpc handler
+ │ └── svc
+ │ └── servicecontext.go // defines service context, like dependencies
+ ├── pb
+ │ └── transform.pb.go
+ ├── transform.go // rpc main entrance
+ ├── transform.proto
+ └── transformer
+ ├── transformer.go // defines how rpc clients call this service
+ ├── transformer_mock.go // mock file, for test purpose
+ └── types.go // request/response definition
+ ```
+
+ just run it, looks like:
+
+ ```shell
+ $ go run transform.go -f etc/transform.yaml
+ Starting rpc server at 127.0.0.1:8080...
+ ```
+
+ you can change the listening port in file `etc/transform.yaml`.
+
+## 7. Modify API Gateway to call transform rpc service
+
+* modify the configuration file `shorturl-api.yaml`, add the following:
+
+ ```yaml
+ Transform:
+ Etcd:
+ Hosts:
+ - localhost:2379
+ Key: transform.rpc
+ ```
+
+ automatically discover the transform service by using etcd.
+
+* modify the file `internal/config/config.go`, add dependency on transform service:
+
+ ```go
+ type Config struct {
+ rest.RestConf
+ Transform zrpc.RpcClientConf // manual code
+ }
+ ```
+
+* modify the file `internal/svc/servicecontext.go`, like below:
+
+ ```go
+ type ServiceContext struct {
+ Config config.Config
+ Transformer transformer.Transformer // manual code
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ Config: c,
+ Transformer: transformer.NewTransformer(zrpc.MustNewClient(c.Transform)), // manual code
+ }
+ }
+ ```
+
+ passing the dependencies among services within ServiceContext.
+
+* modify the method `Expand` in the file `internal/logic/expandlogic.go`, looks like:
+
+ ```go
+ func (l *ExpandLogic) Expand(req types.ExpandReq) (*types.ExpandResp, error) {
+ // manual code start
+ resp, err := l.svcCtx.Transformer.Expand(l.ctx, &transformer.ExpandReq{
+ Shorten: req.Shorten,
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ return &types.ExpandResp{
+ Url: resp.Url,
+ }, nil
+ // manual code stop
+ }
+ ```
+
+ by calling the method `Expand` of `transformer` to restore the shortened url.
+
+* modify the file `internal/logic/shortenlogic.go`, looks like:
+
+ ```go
+ func (l *ShortenLogic) Shorten(req types.ShortenReq) (*types.ShortenResp, error) {
+ // manual code start
+ resp, err := l.svcCtx.Transformer.Shorten(l.ctx, &transformer.ShortenReq{
+ Url: req.Url,
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ return &types.ShortenResp{
+ Shorten: resp.Shorten,
+ }, nil
+ // manual code stop
+ }
+ ```
+
+ by calling the method `Shorten` of `transformer` to shorten the url.
+
+Till now, we’ve done the modification of API Gateway. All the manually added code are marked.
+
+## 8. Define the database schema, generate the code for CRUD+cache
+
+* under shorturl, create the directory `rpc/transform/model`: `mkdir -p rpc/transform/model`
+
+* under the directory rpc/transform/model create the file called shorturl.sql`, contents as below:
+
+ ```sql
+ CREATE TABLE `shorturl`
+ (
+ `shorten` varchar(255) NOT NULL COMMENT 'shorten key',
+ `url` varchar(255) NOT NULL COMMENT 'original url',
+ PRIMARY KEY(`shorten`)
+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+ ```
+
+* create DB and table
+
+ ```sql
+ create database gozero;
+ ```
+
+ ```sql
+ source shorturl.sql;
+ ```
+
+* under the directory `rpc/transform/model` execute the following command to genrate CRUD+cache code, `-c` means using `redis cache`
+
+ ```shell
+ goctl model mysql ddl -c -src shorturl.sql -dir .
+ ```
+
+ you can also generate the code from the database url by using `datasource` subcommand instead of `ddl`
+
+ the generated file structure looks like:
+
+ ```Plain Text
+ rpc/transform/model
+ ├── shorturl.sql
+ ├── shorturlmodel.go // CRUD+cache code
+ └── vars.go // const and var definition
+ ```
+
+## 9. Modify shorten/expand rpc to call crud+cache
+
+* modify `rpc/transform/etc/transform.yaml`, add the following:
+
+ ```yaml
+ DataSource: root:@tcp(localhost:3306)/gozero
+ Table: shorturl
+ Cache:
+ - Host: localhost:6379
+ ```
+
+ you can use multiple redis as cache. redis node and cluster are both supported.
+
+* modify `rpc/transform/internal/config.go`, like below:
+
+ ```go
+ type Config struct {
+ zrpc.RpcServerConf
+ DataSource string // manual code
+ Table string // manual code
+ Cache cache.CacheConf // manual code
+ }
+ ```
+
+ added the configuration for mysql and redis cache.
+
+* modify `rpc/transform/internal/svc/servicecontext.go`, like below:
+
+ ```go
+ type ServiceContext struct {
+ c config.Config
+ Model model.ShorturlModel // manual code
+ }
+
+ func NewServiceContext(c config.Config) *ServiceContext {
+ return &ServiceContext{
+ c: c,
+ Model: model.NewShorturlModel(sqlx.NewMysql(c.DataSource), c.Cache, c.Table), // manual code
+ }
+ }
+ ```
+
+* modify `rpc/transform/internal/logic/expandlogic.go`, like below:
+
+ ```go
+ func (l *ExpandLogic) Expand(in *transform.ExpandReq) (*transform.ExpandResp, error) {
+ // manual code start
+ res, err := l.svcCtx.Model.FindOne(in.Shorten)
+ if err != nil {
+ return nil, err
+ }
+
+ return &transform.ExpandResp{
+ Url: res.Url,
+ }, nil
+ // manual code stop
+ }
+ ```
+
+* modify `rpc/shorten/internal/logic/shortenlogic.go`, looks like:
+
+ ```go
+ func (l *ShortenLogic) Shorten(in *transform.ShortenReq) (*transform.ShortenResp, error) {
+ // manual code start, generates shorturl
+ key := hash.Md5Hex([]byte(in.Url))[:6]
+ _, err := l.svcCtx.Model.Insert(model.Shorturl{
+ Shorten: key,
+ Url: in.Url,
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ return &transform.ShortenResp{
+ Shorten: key,
+ }, nil
+ // manual code stop
+ }
+ ```
+
+ till now, we finished modifing the code, all the modified code is marked.
+
+## 10. Call shorten and expand services
+
+* call shorten api
+
+ ```shell
+ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn"
+ ```
+
+ response like:
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sat, 29 Aug 2020 10:49:49 GMT
+ Content-Length: 21
+
+ {"shorten":"f35b2a"}
+ ```
+
+* call expand api
+
+ ```shell
+ curl -i "http://localhost:8888/expand?shorten=f35b2a"
+ ```
+
+ response like:
+
+ ```http
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Date: Sat, 29 Aug 2020 10:51:53 GMT
+ Content-Length: 34
+
+ {"url":"http://www.xiaoheiban.cn"}
+ ```
+
+## 11. Benchmark
+
+Because benchmarking the write requests depends on the write throughput of mysql, we only benchmarked the expand api. We read the data from mysql and cache it in redis. I chose 100 hot keys hardcoded in shorten.lua to generate the benchmark.
+
+
+
+as shown above, in my MacBook Pro, the QPS is like 30K+.
+
+## 12. Full code
+
+[https://github.com/zeromicro/zero-examples/tree/main/shorturl](https://github.com/zeromicro/zero-examples/tree/main/shorturl)
+
+## 13. Conclusion
+
+We always adhere to **prefer tools over conventions and documents**.
+
+go-zero is not only a framework, but also a tool to simplify and standardize the building of micoservice systems.
+
+We not only keep the framework simple, but also encapsulate the complexity into the framework. And the developers are free from building the difficult and boilerplate code. Then we get the rapid development and less failure.
+
+For the generated code by goctl, lots of microservice components are included, like concurrency control, adaptive circuit breaker, adaptive load shedding, auto cache control etc. And it’s easy to deal with the busy sites.
+
+If you have any ideas that can help us to improve the productivity, tell me any time! 👏
diff --git a/go-zero.dev/en/source.md b/go-zero.dev/en/source.md
new file mode 100644
index 00000000..1f1d75d4
--- /dev/null
+++ b/go-zero.dev/en/source.md
@@ -0,0 +1,5 @@
+# Source Code
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+* [demo](https://github.com/zeromicro/go-zero-demo)
\ No newline at end of file
diff --git a/go-zero.dev/en/stream.md b/go-zero.dev/en/stream.md
new file mode 100644
index 00000000..1184c529
--- /dev/null
+++ b/go-zero.dev/en/stream.md
@@ -0,0 +1,367 @@
+# Stream processing
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+Stream processing is a computer programming paradigm that allows given a data sequence (stream processing data source), a series of data operations (functions) are applied to each element in the stream. At the same time, stream processing tools can significantly improve programmers' development efficiency, allowing them to write effective, clean, and concise code.
+
+Streaming data processing is very common in our daily work. For example, we often record many business logs in business development. These logs are usually sent to Kafka first, and then written to elasticsearch by the Job consumption Kafka, and the logs are in progress. In the process of stream processing, logs are often processed, such as filtering invalid logs, doing some calculations and recombining logs, etc. The schematic diagram is as follows:
+
+### fx
+[go-zero](https://github.com/zeromicro/go-zero) is a full-featured microservice framework. There are many very useful tools built in the framework, including streaming data processing tools [fx ](https://github.com/zeromicro/go-zero/tree/master/core/fx), let’s use a simple example to understand the tool:
+```go
+package main
+
+import (
+ "fmt"
+ "os"
+ "os/signal"
+ "syscall"
+ "time"
+
+ "github.com/tal-tech/go-zero/core/fx"
+)
+
+func main() {
+ ch := make(chan int)
+
+ go inputStream(ch)
+ go outputStream(ch)
+
+ c := make(chan os.Signal, 1)
+ signal.Notify(c, syscall.SIGTERM, syscall.SIGINT)
+ <-c
+}
+
+func inputStream(ch chan int) {
+ count := 0
+ for {
+ ch <- count
+ time.Sleep(time.Millisecond * 500)
+ count++
+ }
+}
+
+func outputStream(ch chan int) {
+ fx.From(func(source chan<- interface{}) {
+ for c := range ch {
+ source <- c
+ }
+ }).Walk(func(item interface{}, pipe chan<- interface{}) {
+ count := item.(int)
+ pipe <- count
+ }).Filter(func(item interface{}) bool {
+ itemInt := item.(int)
+ if itemInt%2 == 0 {
+ return true
+ }
+ return false
+ }).ForEach(func(item interface{}) {
+ fmt.Println(item)
+ })
+}
+```
+
+
+The inputStream function simulates the generation of stream data, and the outputStream function simulates the process of stream data. The From function is the input of the stream. The Walk function concurrently acts on each item. The Filter function filters the item as true and keeps it as false. Keep, the ForEach function traverses and outputs each item element.
+
+
+### Intermediate operations of streaming data processing
+
+
+There may be many intermediate operations in the data processing of a stream, and each intermediate operation can act on the stream. Just like the workers on the assembly line, each worker will return to the processed new part after operating the part, and in the same way, after the intermediate operation of the flow processing is completed, it will also return to a new flow.
+
+Intermediate operations of fx stream processing:
+
+| Operation function | Features | Input |
+| --- | --- | --- |
+| Distinct | Remove duplicate items | KeyFunc, return the key that needs to be deduplicated |
+| Filter | Filter items that do not meet the conditions | FilterFunc, Option controls the amount of concurrency |
+| Group | Group items | KeyFunc, group by key |
+| Head | Take out the first n items and return to the new stream | int64 reserved number |
+| Map | Object conversion | MapFunc, Option controls the amount of concurrency |
+| Merge | Merge item into slice and generate new stream | |
+| Reverse | Reverse item | |
+| Sort | Sort items | LessFunc implements sorting algorithm |
+| Tail | Similar to the Head function, n items form a new stream after being taken out | int64 reserved number |
+| Walk | Act on each item | WalkFunc, Option controls the amount of concurrency |
+
+
+
+The following figure shows each step and the result of each step:
+
+
+
+
+
+### Usage and principle analysis
+
+
+#### From
+
+
+Construct a stream through the From function and return the Stream, and the stream data is stored through the channel:
+
+
+```go
+// Example
+s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 0}
+fx.From(func(source chan<- interface{}) {
+ for _, v := range s {
+ source <- v
+ }
+})
+
+// Source Code
+func From(generate GenerateFunc) Stream {
+ source := make(chan interface{})
+
+ threading.GoSafe(func() {
+ defer close(source)
+ generate(source)
+ })
+
+ return Range(source)
+}
+```
+
+
+#### Filter
+
+
+The Filter function provides the function of filtering items, FilterFunc defines the filtering logic true to retain the item, and false to not retain:
+
+
+```go
+// Example: Keep even numbers
+s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 0}
+fx.From(func(source chan<- interface{}) {
+ for _, v := range s {
+ source <- v
+ }
+}).Filter(func(item interface{}) bool {
+ if item.(int)%2 == 0 {
+ return true
+ }
+ return false
+})
+
+// Source Code
+func (p Stream) Filter(fn FilterFunc, opts ...Option) Stream {
+ return p.Walk(func(item interface{}, pipe chan<- interface{}) {
+ // Execute the filter function true to retain, false to discard
+ if fn(item) {
+ pipe <- item
+ }
+ }, opts...)
+}
+```
+
+
+#### Group
+
+
+Group groups the stream data. The key of the group needs to be defined. After the data is grouped, it is stored in the channel as slices:
+
+
+```go
+// Example Group according to the first character "g" or "p", if not, it will be divided into another group
+ ss := []string{"golang", "google", "php", "python", "java", "c++"}
+ fx.From(func(source chan<- interface{}) {
+ for _, s := range ss {
+ source <- s
+ }
+ }).Group(func(item interface{}) interface{} {
+ if strings.HasPrefix(item.(string), "g") {
+ return "g"
+ } else if strings.HasPrefix(item.(string), "p") {
+ return "p"
+ }
+ return ""
+ }).ForEach(func(item interface{}) {
+ fmt.Println(item)
+ })
+}
+
+// Source Code
+func (p Stream) Group(fn KeyFunc) Stream {
+ // Define group storage map
+ groups := make(map[interface{}][]interface{})
+ for item := range p.source {
+ // User-defined group key
+ key := fn(item)
+ // Group the same key into a group
+ groups[key] = append(groups[key], item)
+ }
+
+ source := make(chan interface{})
+ go func() {
+ for _, group := range groups {
+ // A group of data with the same key is written to the channel
+ source <- group
+ }
+ close(source)
+ }()
+
+ return Range(source)
+}
+```
+
+
+#### Reverse
+
+
+reverse can reverse the elements in the stream:
+
+
+
+
+
+```go
+// Example
+fx.Just(1, 2, 3, 4, 5).Reverse().ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+
+// Source Code
+func (p Stream) Reverse() Stream {
+ var items []interface{}
+ // Get the data in the stream
+ for item := range p.source {
+ items = append(items, item)
+ }
+ // Reversal algorithm
+ for i := len(items)/2 - 1; i >= 0; i-- {
+ opp := len(items) - 1 - i
+ items[i], items[opp] = items[opp], items[i]
+ }
+
+ // Write stream
+ return Just(items...)
+}
+```
+
+
+#### Distinct
+
+
+Distinct de-duplicates elements in the stream. De-duplication is commonly used in business development. It is often necessary to de-duplicate user IDs, etc.:
+
+
+```go
+// Example
+fx.Just(1, 2, 2, 2, 3, 3, 4, 5, 6).Distinct(func(item interface{}) interface{} {
+ return item
+}).ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+// Output: 1，2，3，4，5，6
+
+// Source Code
+func (p Stream) Distinct(fn KeyFunc) Stream {
+ source := make(chan interface{})
+
+ threading.GoSafe(func() {
+ defer close(source)
+ // Deduplication is performed by key, and only one of the same key is kept
+ keys := make(map[interface{}]lang.PlaceholderType)
+ for item := range p.source {
+ key := fn(item)
+ // The key is not retained if it exists
+ if _, ok := keys[key]; !ok {
+ source <- item
+ keys[key] = lang.Placeholder
+ }
+ }
+ })
+
+ return Range(source)
+}
+```
+
+
+#### Walk
+
+
+The concurrency of the Walk function works on each item in the stream. You can set the number of concurrency through WithWorkers. The default number of concurrency is 16, and the minimum number of concurrency is 1. If you set unlimitedWorkers to true, the number of concurrency is unlimited, but the number of concurrent writes in the stream is unlimited. The data is limited by defaultWorkers. In WalkFunc, users can customize the elements that are subsequently written to the stream, and can write multiple elements without writing:
+
+
+```go
+// Example
+fx.Just("aaa", "bbb", "ccc").Walk(func(item interface{}, pipe chan<- interface{}) {
+ newItem := strings.ToUpper(item.(string))
+ pipe <- newItem
+}).ForEach(func(item interface{}) {
+ fmt.Println(item)
+})
+
+// Source Code
+func (p Stream) walkLimited(fn WalkFunc, option *rxOptions) Stream {
+ pipe := make(chan interface{}, option.workers)
+
+ go func() {
+ var wg sync.WaitGroup
+ pool := make(chan lang.PlaceholderType, option.workers)
+
+ for {
+ // Control the number of concurrent
+ pool <- lang.Placeholder
+ item, ok := <-p.source
+ if !ok {
+ <-pool
+ break
+ }
+
+ wg.Add(1)
+ go func() {
+ defer func() {
+ wg.Done()
+ <-pool
+ }()
+ // Acting on every element
+ fn(item, pipe)
+ }()
+ }
+
+ // Wait for processing to complete
+ wg.Wait()
+ close(pipe)
+ }()
+
+ return Range(pipe)
+}
+```
+
+
+### Concurrent processing
+
+
+In addition to stream data processing, the fx tool also provides function concurrency. The realization of a function in microservices often requires multiple services. Concurrent processing dependence can effectively reduce dependency time and improve service performance.
+
+
+
+
+
+```go
+fx.Parallel(func() {
+ userRPC()
+}, func() {
+ accountRPC()
+}, func() {
+ orderRPC()
+})
+```
+
+
+Note that when fx.Parallel performs dependency parallel processing, there will be no error return. If you need an error return, or a dependency error report needs to end the dependency request immediately, please use the [MapReduce](https://gocn.vip/topics/10941) tool To process.
+
+
+### Summary
+
+
+This article introduces the basic concepts of stream processing and the stream processing tool fx in go-zero. There are many stream processing scenarios in actual production. I hope this article can give you some inspiration and better response Stream processing scene at work.
+
+
+
+
+
+
diff --git a/go-zero.dev/en/summary.md b/go-zero.dev/en/summary.md
new file mode 100644
index 00000000..d0114eb4
--- /dev/null
+++ b/go-zero.dev/en/summary.md
@@ -0,0 +1,84 @@
+# Summary
+
+* [Introduction](README.md)
+* [About Us](about-us.md)
+* [Join Us](join-us.md)
+* [Concepts](concept-introduction.md)
+* [Quick Start](quick-start.md)
+ * [Monolithic Service](monolithic-service.md)
+ * [Micro Service](micro-service.md)
+* [Framework Design](framework-design.md)
+ * [Go-Zero Design](go-zero-design.md)
+ * [Go-Zero Features](go-zero-features.md)
+ * [API IDL](api-grammar.md)
+ * [API Directory Structure](api-dir.md)
+ * [RPC Directory Structure](rpc-dir.md)
+* [Project Development](project-dev.md)
+ * [Prepare](prepare.md)
+ * [Golang Installation](golang-install.md)
+ * [Go Module Configuration](gomod-config.md)
+ * [Goctl Installation](goctl-install.md)
+ * [protoc & protoc-gen-go Installation](protoc-install.md)
+ * [More](prepare-other.md)
+ * [Development Rules](dev-specification.md)
+ * [Naming Rules](naming-spec.md)
+ * [Route Rules](route-naming-spec.md)
+ * [Coding Rules](coding-spec.md)
+ * [Development Flow](dev-flow.md)
+ * [Configuration Introduction](config-introduction.md)
+ * [API Configuration](api-config.md)
+ * [RPC Configuration](rpc-config.md)
+ * [Business Development](business-dev.md)
+ * [Directory Structure](service-design.md)
+ * [Model Generation](model-gen.md)
+ * [API Coding](api-coding.md)
+ * [Business Coding](business-coding.md)
+ * [JWT](jwt.md)
+ * [Middleware](middleware.md)
+ * [RPC Implement & Call](rpc-call.md)
+ * [Error Handling](error-handle.md)
+ * [CI/CD](ci-cd.md)
+ * [Service Deployment](service-deployment.md)
+ * [Log Collection](log-collection.md)
+ * [Trace](trace.md)
+ * [Monitor](service-monitor.md)
+* [Goctl](goctl.md)
+ * [Commands & Flags](goctl-commands.md)
+ * [API Commands](goctl-api.md)
+ * [RPC Commands](goctl-rpc.md)
+ * [Model Commands](goctl-model.md)
+ * [Plugin Commands](goctl-plugin.md)
+ * [More Commands](goctl-other.md)
+* [Template](template-manage.md)
+ * [Command](template-cmd.md)
+ * [Custom](template.md)
+* [Extended](extended-reading.md)
+ * [logx](logx.md)
+ * [bloom](bloom.md)
+ * [executors](executors.md)
+ * [fx](fx.md)
+ * [mysql](mysql.md)
+ * [redis-lock](redis-lock.md)
+ * [periodlimit](periodlimit.md)
+ * [tokenlimit](tokenlimit.md)
+ * [TimingWheel](timing-wheel.md)
+* [Tools](tool-center.md)
+ * [Intellij Plugin](intellij.md)
+ * [VSCode Plugin](vscode.md)
+* [Plugins](plugin-center.md)
+* [Learning Resources](learning-resource.md)
+ * [Wechat](wechat.md)
+ * [Night](goreading.md)
+ * [OpenTalk](gotalk.md)
+* [User Practise](practise.md)
+ * [Persistent layer cache](redis-cache.md)
+ * [Business layer cache](buiness-cache.md)
+ * [Queue](go-queue.md)
+ * [Middle Ground System](datacenter.md)
+ * [Stream Handler](stream.md)
+ * [Online Exchange](online-exchange.md)
+* [Contributor](contributor.md)
+* [Document Contribute](doc-contibute.md)
+* [Error](error.md)
+* [Source Code](source.md)
+
diff --git a/go-zero.dev/en/template-cmd.md b/go-zero.dev/en/template-cmd.md
new file mode 100644
index 00000000..ec7429b7
--- /dev/null
+++ b/go-zero.dev/en/template-cmd.md
@@ -0,0 +1,113 @@
+# Template Operation
+
+Template is the basis of data-driven generation, all code (rest api, rpc, model, docker, kube) generation will rely on template.
+By default, the template generator selects the in-memory template for generation, while for developers who need to modify the template, they need to drop the template and make template changes in the next code generation.
+For developers who need to modify the templates, they need to modify the templates, and then the next time the code is generated, it will load the templates under the specified path to generate.
+
+## Help
+```text
+NAME:
+ goctl template - template operation
+
+USAGE:
+ goctl template command [command options] [arguments...]
+
+COMMANDS:
+ init initialize the all templates(force update)
+ clean clean the all cache templates
+ update update template of the target category to the latest
+ revert revert the target template to the latest
+
+OPTIONS:
+ --help, -h show help
+```
+
+## Init
+```text
+NAME:
+ goctl template init - initialize the all templates(force update)
+
+USAGE:
+ goctl template init [command options] [arguments...]
+
+OPTIONS:
+ --home value the goctl home path of the template
+```
+
+## Clean
+```text
+NAME:
+ goctl template clean - clean the all cache templates
+
+USAGE:
+ goctl template clean [command options] [arguments...]
+
+OPTIONS:
+ --home value the goctl home path of the template
+```
+
+## Update
+```text
+NAME:
+ goctl template update - update template of the target category to the latest
+
+USAGE:
+ goctl template update [command options] [arguments...]
+
+OPTIONS:
+ --category value, -c value the category of template, enum [api,rpc,model,docker,kube]
+ --home value the goctl home path of the template
+```
+
+## Revert
+```text
+NAME:
+ goctl template revert - revert the target template to the latest
+
+USAGE:
+ goctl template revert [command options] [arguments...]
+
+OPTIONS:
+ --category value, -c value the category of template, enum [api,rpc,model,docker,kube]
+ --name value, -n value the target file name of template
+ --home value the goctl home path of the template
+```
+
+> [!TIP]
+>
+> `--home` Specify the template storage path
+
+## Template loading
+
+You can specify the folder where the template is located by `--home` during code generation, and the commands that have been supported to specify the template directory are
+
+- `goctl api go` Details can be found in `goctl api go --help` for help
+- `goctl docker` Details can be viewed with `goctl docker --help`
+- `goctl kube` Details can be viewed with `goctl kube --help`
+- `goctl rpc new` Details can be viewed with `goctl rpc new --help`
+- `goctl rpc proto` Details can be viewed with `goctl rpc proto --help`
+- `goctl model mysql ddl` Details can be viewed with `goctl model mysql ddl --help`
+- `goctl model mysql datasource` Details can be viewed with `goctl model mysql datasource --help`
+- `goctl model postgresql datasource` Details can be viewed with `goctl model mysql datasource --help`
+- `goctl model mongo` Details can be viewed with `goctl model mongo --help`
+
+The default (when `--home` is not specified) is to read from the `$HOME/.goctl` directory.
+
+## Example
+* Initialize the template to the specified `$HOME/template` directory
+```text
+$ goctl template init --home $HOME/template
+```
+
+```text
+Templates are generated in /Users/anqiansong/template, edit on your risk!
+```
+
+* Greet rpc generation using `$HOME/template` template
+```text
+$ goctl rpc new greet --home $HOME/template
+```
+
+```text
+Done
+```
\ No newline at end of file
diff --git a/go-zero.dev/en/template-manage.md b/go-zero.dev/en/template-manage.md
new file mode 100644
index 00000000..acfd5251
--- /dev/null
+++ b/go-zero.dev/en/template-manage.md
@@ -0,0 +1,4 @@
+# Template
+
+- [Command](template-cmd.md)
+- [Custom](template.md)
\ No newline at end of file
diff --git a/go-zero.dev/en/template.md b/go-zero.dev/en/template.md
new file mode 100644
index 00000000..7e122e31
--- /dev/null
+++ b/go-zero.dev/en/template.md
@@ -0,0 +1,160 @@
+# Template Modification
+
+## Scenario
+Implement a uniformly formatted body accordingly, in the following format.
+```json
+{
+ "code": 0,
+ "msg": "OK",
+ "data": {}// ①
+}
+```
+
+① 实际相应数据
+
+> [!TIP]
+> The code generated by `go-zero` does not process it
+
+## Preparation
+We go ahead and write a `Response` method in the `response` package under the project with `module` as `greet`, with a directory tree similar to the following.
+```text
+greet
+├── reponse
+│ └── response.go
+└── xxx...
+```
+
+The code is as follows
+```go
+package reponse
+
+import (
+ "net/http"
+
+ "github.com/tal-tech/go-zero/rest/httpx"
+)
+
+type Body struct {
+ Code int `json:"code"`
+ Msg string `json:"msg"`
+ Data interface{} `json:"data,omitempty"`
+}
+
+func Response(w http.ResponseWriter, resp interface{}, err error) {
+ var body Body
+ if err != nil {
+ body.Code = -1
+ body.Msg = err.Error()
+ } else {
+ body.Msg = "OK"
+ body.Data = resp
+ }
+ httpx.OkJson(w, body)
+}
+```
+
+## Modify the `handler` template
+```shell
+$ vim ~/.goctl/api/handler.tpl
+```
+
+Replace the template with the following
+```go
+package handler
+
+import (
+ "net/http"
+ "greet/response"// ①
+
+ {{.ImportPackages}}
+)
+
+func {{.HandlerName}}(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ {{if .HasRequest}}var req types.{{.RequestType}}
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }{{end}}
+
+ l := logic.New{{.LogicType}}(r.Context(), ctx)
+ {{if .HasResp}}resp, {{end}}err := l.{{.Call}}({{if .HasRequest}}req{{end}})
+ {{if .HasResp}}reponse.Response(w, resp, err){{else}}reponse.Response(w, nil, err){{end}}//②
+
+ }
+}
+```
+
+① Replace with your real `response` package name, for reference only
+
+② Customized template content
+
+> [!TIP]
+>
+> 1.If there is no local `~/.goctl/api/handler.tpl` file, you can initialize it with the template initialization command `goctl template init`
+
+## Comparison
+* Before
+```go
+func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ var req types.Request
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }
+
+ l := logic.NewGreetLogic(r.Context(), ctx)
+ resp, err := l.Greet(req)
+ // The following content will be replaced by custom templates
+ if err != nil {
+ httpx.Error(w, err)
+ } else {
+ httpx.OkJson(w, resp)
+ }
+ }
+}
+```
+* After
+```go
+func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ var req types.Request
+ if err := httpx.Parse(r, &req); err != nil {
+ httpx.Error(w, err)
+ return
+ }
+
+ l := logic.NewGreetLogic(r.Context(), ctx)
+ resp, err := l.Greet(req)
+ reponse.Response(w, resp, err)
+ }
+}
+```
+
+## Comparison of response body
+
+* Before
+```json
+{
+ "message": "Hello go-zero!"
+}
+```
+
+* After
+```json
+{
+ "code": 0,
+ "msg": "OK",
+ "data": {
+ "message": "Hello go-zero!"
+ }
+}
+```
+
+# Summary
+This document only describes the process of customizing the template for the corresponding example of http, in addition to the following scenarios of customizing the template.
+* model layer adds kmq
+* model layer to generate the model instance of the option to be valid
+* http customize the corresponding format
+ ...
\ No newline at end of file
diff --git a/go-zero.dev/en/timing-wheel.md b/go-zero.dev/en/timing-wheel.md
new file mode 100644
index 00000000..6b4ec3b3
--- /dev/null
+++ b/go-zero.dev/en/timing-wheel.md
@@ -0,0 +1,321 @@
+# TimingWheel
+> [!TIP]
+> This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please [PR](doc-contibute.md)
+
+This article introduces the **delayed operation** in `go-zero`. **Delayed operation**, two options can be used:
+
+
+1. `Timer`: The timer maintains a priority queue, executes it at the time, and then stores the tasks that need to be executed in the map
+2. The `timingWheel` in `collection` maintains an array for storing task groups, and each slot maintains a doubly linked list of tasks. When the execution starts, the timer executes the tasks in a slot every specified time.
+
+
+
+Scheme 2 reduces the maintenance task from the `priority queue O(nlog(n))` to the `doubly linked list O(1)`, and the execution of the task only needs to poll the tasks `O(N)` at a time point. Priority queue, put and delete elements `O(nlog(n))`.
+
+
+## timingWheel in cache
+
+
+First, let's first talk about the use of TimingWheel in the cache of collection:
+
+
+```go
+timingWheel, err := NewTimingWheel(time.Second, slots, func(k, v interface{}) {
+ key, ok := k.(string)
+ if !ok {
+ return
+ }
+ cache.Del(key)
+})
+if err != nil {
+ return nil, err
+}
+
+cache.timingWheel = timingWheel
+```
+
+
+This is the initialization of `cache` and the initialization of `timingWheel` at the same time for key expiration processing. The parameters in turn represent:
+
+
+- `interval`: Time division scale
+- `numSlots`: time slots
+- `execute`: execute a function at a point in time
+
+
+
+The function executed in the `cache` is to **delete the expired key**, and this expiration is controlled by the `timingWheel` to advance the time.
+
+
+**Next, let's learn about it through the use of timingWheel by cache. **
+
+
+### Initialization
+
+
+```go
+func newTimingWheelWithClock(interval time.Duration, numSlots int, execute Execute, ticker timex.Ticker) (
+ *TimingWheel, error) {
+ tw := &TimingWheel{
+ interval: interval, // Single time grid time interval
+ ticker: ticker, // Timer, do time push, advance by interval
+ slots: make([]*list.List, numSlots), // Time wheel
+ timers: NewSafeMap(), // Store the map of task{key, value} [parameters needed to execute execute]
+ tickedPos: numSlots - 1, // at previous virtual circle
+ execute: execute, // Execution function
+ numSlots: numSlots, // Initialize slots num
+ setChannel: make(chan timingEntry), // The following channels are used for task delivery
+ moveChannel: make(chan baseEntry),
+ removeChannel: make(chan interface{}),
+ drainChannel: make(chan func(key, value interface{})),
+ stopChannel: make(chan lang.PlaceholderType),
+ }
+ // Prepare all the lists stored in the slot
+ tw.initSlots()
+ // Open asynchronous coroutine, use channel for task communication and delivery
+ go tw.run()
+
+ return tw, nil
+}
+```
+
+
+
+
+
+The above is a more intuitive display of the **"time wheel"** of the `timingWheel`, and the details of the advancement will be explained later around this picture.
+
+
+`go tw.run()` opens a coroutine for time promotion:
+
+
+```go
+func (tw *TimingWheel) run() {
+ for {
+ select {
+ // Timer do time push -> scanAndRunTasks()
+ case <-tw.ticker.Chan():
+ tw.onTick()
+ // add task will enter task into setChannel
+ case task := <-tw.setChannel:
+ tw.setTask(&task)
+ ...
+ }
+ }
+}
+```
+
+
+It can be seen that the `timer` execution is started at the time of initialization, and it is rotated in the `internal` time period, and then the bottom layer keeps getting the tasks from the `list` in the `slot` and handing them over to the `execute` for execution.
+
+
+
+
+
+### Task Operation
+
+
+The next step is to set the `cache key`:
+
+
+```go
+func (c *Cache) Set(key string, value interface{}) {
+ c.lock.Lock()
+ _, ok := c.data[key]
+ c.data[key] = value
+ c.lruCache.add(key)
+ c.lock.Unlock()
+
+ expiry := c.unstableExpiry.AroundDuration(c.expire)
+ if ok {
+ c.timingWheel.MoveTimer(key, expiry)
+ } else {
+ c.timingWheel.SetTimer(key, value, expiry)
+ }
+}
+```
+
+
+1. First look at whether this key exists in the `data map`
+1. If it exists, update `expire` -> `MoveTimer()`
+1. Set the key for the first time -> `SetTimer()`
+
+
+
+So the use of `timingWheel` is clear. Developers can `add` or `update` according to their needs.
+
+
+At the same time, when we follow the source code, we will find that: `SetTimer() MoveTimer()` all transports tasks to channel, and the coroutine opened in `run()` continuously takes out the task operations of `channel`.
+
+
+> `SetTimer() -> setTask()`：
+> - not exist task：`getPostion -> pushBack to list -> setPosition`
+> - exist task：`get from timers -> moveTask()`
+>
+`MoveTimer() -> moveTask()`
+
+
+
+From the above call chain, there is a function that will be called: `moveTask()`
+
+
+```go
+func (tw *TimingWheel) moveTask(task baseEntry) {
+ // timers: Map => Get [positionEntry「pos, task」] by key
+ val, ok := tw.timers.Get(task.key)
+ if !ok {
+ return
+ }
+
+ timer := val.(*positionEntry)
+ // {delay | Name | +Author | +QrCode | +
| 微服务实战 | +kevwan | + |
+