From 91bfc093f4fa68901c13051271b65973a88a9278 Mon Sep 17 00:00:00 2001 From: maiyang Date: Thu, 22 Oct 2020 22:24:35 +0800 Subject: [PATCH] docs: format markdown and add go mod in demo (#155) --- readme-en.md | 2 + readme.md | 117 +++++++++++++++++++++++++++------------------------ 2 files changed, 63 insertions(+), 56 deletions(-) diff --git a/readme-en.md b/readme-en.md index 969bf3f8..4713000e 100644 --- a/readme-en.md +++ b/readme-en.md @@ -164,6 +164,8 @@ go get -u github.com/tal-tech/go-zero ```shell cd greet + go mod init + go mod tidy go run greet.go -f etc/greet-api.yaml ``` diff --git a/readme.md b/readme.md index 269b912b..761c4f95 100644 --- a/readme.md +++ b/readme.md @@ -8,28 +8,28 @@ [![Release](https://img.shields.io/github/v/release/tal-tech/go-zero.svg?style=flat-square)](https://github.com/tal-tech/go-zero) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -## 0. go-zero介绍 +## 0. go-zero 介绍 -go-zero是一个集成了各种工程实践的web和rpc框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。 +go-zero 是一个集成了各种工程实践的 web 和 rpc 框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。 go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 api 文件一键生成 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 代码，并可直接运行。 -使用go-zero的好处： +使用 go-zero 的好处： * 轻松获得支撑千万日活服务的稳定性 * 内建级联超时控制、限流、自适应熔断、自适应降载等微服务治理能力，无需配置和额外代码 * 微服务治理中间件可无缝集成到其它现有框架使用 -* 极简的API描述，一键生成各端代码 +* 极简的 API 描述，一键生成各端代码 * 自动校验客户端请求参数合法性 * 大量微服务治理和并发工具包 架构图 -## 1. go-zero框架背景 +## 1. go-zero 框架背景 -18年初，我们决定从`Java+MongoDB`的单体架构迁移到微服务架构，经过仔细思考和对比，我们决定： +18 年初，我们决定从 `Java+MongoDB` 的单体架构迁移到微服务架构，经过仔细思考和对比，我们决定： -* 基于Go语言 +* 基于 Go 语言 * 高效的性能 * 简洁的语法 * 广泛验证的工程效率 @@ -40,7 +40,7 @@ go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 * 需要有更快速的问题定位能力 * 更便捷的增加新特性 -## 2. go-zero框架设计思考 +## 2. go-zero 框架设计思考 对于微服务框架的设计，我们期望保障微服务稳定性的同时，也要特别注重研发效率。所以设计之初，我们就有如下一些准则： @@ -53,21 +53,21 @@ go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 * 对业务开发友好，封装复杂度 * 约束做一件事只有一种方式 -我们经历不到半年时间，彻底完成了从`Java+MongoDB`到`Golang+MySQL`为主的微服务体系迁移，并于18年8月底完全上线，稳定保障了业务后续迅速增长，确保了整个服务的高可用。 +我们经历不到半年时间，彻底完成了从 `Java+MongoDB` 到 `Golang+MySQL` 为主的微服务体系迁移，并于 18 年 8 月底完全上线，稳定保障了业务后续迅速增长，确保了整个服务的高可用。 -## 3. go-zero项目实现和特点 +## 3. go-zero 项目实现和特点 -go-zero是一个集成了各种工程实践的包含web和rpc框架，有如下主要特点： +go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有如下主要特点： * 强大的工具支持，尽可能少的代码编写 * 极简的接口 -* 完全兼容net/http +* 完全兼容 net/http * 支持中间件，方便扩展 * 高性能 * 面向故障编程，弹性设计 * 内建服务发现、负载均衡 * 内建限流、熔断、降载，且自动触发，自动恢复 -* API参数自动校验 +* API 参数自动校验 * 超时级联控制 * 自动缓存控制 * 链路跟踪、统计报警等 @@ -91,53 +91,58 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/ [快速构建高并发微服务](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl.md) - [快速构建高并发微服务-多RPC版](https://github.com/tal-tech/zero-doc/blob/main/doc/bookstore.md) + [快速构建高并发微服务 - 多 RPC 版](https://github.com/tal-tech/zero-doc/blob/main/doc/bookstore.md) -1. 安装goctl工具 +1. 安装 goctl 工具 - `goctl`读作`go control`，不要读成`go C-T-L`。`goctl`的意思是不要被代码控制，而是要去控制它。其中的`go`不是指`golang`。在设计`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 - ``` + ```shell + GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl + ``` - 确保goctl可执行 + 确保 goctl 可执行 -2. 快速生成api服务 +2. 快速生成 api 服务 - ```shell - goctl api new greet - cd greet - go run greet.go -f etc/greet-api.yaml - ``` + ```shell + goctl api new greet + cd greet + go mod init + go mod tidy + go run greet.go -f etc/greet-api.yaml + ``` - 默认侦听在8888端口（可以在配置文件里修改），可以通过curl请求： + 默认侦听在 8888 端口（可以在配置文件里修改），可以通过 curl 请求： - ```shell - curl -i http://localhost:8888/greet/from/you - ``` + ```shell + curl -i http://localhost:8888/greet/from/you + ``` - 返回如下： + 返回如下： - ```http - HTTP/1.1 200 OK - Date: Sun, 30 Aug 2020 15:32:35 GMT - Content-Length: 0 - ``` + ```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代码 + * 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 里增加业务处理逻辑 - ```shell - goctl api java -api greet.api -dir greet - goctl api dart -api greet.api -dir greet - ... - ``` +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 @@ -147,32 +152,32 @@ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/ ## 7. 文档 -* API文档 (逐步完善中) +* API 文档 (逐步完善中) [https://www.yuque.com/tal-tech/go-zero](https://www.yuque.com/tal-tech/go-zero) -* awesome系列 +* awesome 系列 * [快速构建高并发微服务](https://github.com/tal-tech/zero-doc/blob/main/doc/shorturl.md) - * [快速构建高并发微服务-多RPC版](https://github.com/tal-tech/zero-doc/blob/main/doc/bookstore.md) - * [goctl使用帮助](https://github.com/tal-tech/zero-doc/blob/main/doc/goctl.md) - * [通过MapReduce降低服务响应时间](https://github.com/tal-tech/zero-doc/blob/main/doc/mapreduce.md) + * [快速构建高并发微服务 - 多 RPC 版](https://github.com/tal-tech/zero-doc/blob/main/doc/bookstore.md) + * [goctl 使用帮助](https://github.com/tal-tech/zero-doc/blob/main/doc/goctl.md) + * [通过 MapReduce 降低服务响应时间](https://github.com/tal-tech/zero-doc/blob/main/doc/mapreduce.md) * [关键字替换和敏感词过滤工具](https://github.com/tal-tech/zero-doc/blob/main/doc/keywords.md) * [进程内缓存使用方法](https://github.com/tal-tech/zero-doc/blob/main/doc/collection.md) * [防止缓存击穿之进程内共享调用](https://github.com/tal-tech/zero-doc/blob/main/doc/sharedcalls.md) - * [基于prometheus的微服务指标监控](https://github.com/tal-tech/zero-doc/blob/main/doc/metric.md) + * [基于 prometheus 的微服务指标监控](https://github.com/tal-tech/zero-doc/blob/main/doc/metric.md) * [文本序列化和反序列化](https://github.com/tal-tech/zero-doc/blob/main/doc/mapping.md) - * [快速构建jwt鉴权认证](https://github.com/tal-tech/zero-doc/blob/main/doc/jwt.md) + * [快速构建 jwt 鉴权认证](https://github.com/tal-tech/zero-doc/blob/main/doc/jwt.md) ## 9. 微信交流群 -加群之前有劳给一个star，一个小小的star是作者们回答海量问题的动力。 +加群之前有劳给一个 star，一个小小的 star 是作者们回答海量问题的动力。 如果文档中未能覆盖的任何疑问，欢迎您在群里提出，我们会尽快答复。 您可以在群内提出使用中需要改进的地方，我们会考虑合理性并尽快修改。 -如果您发现bug请及时提issue，我们会尽快确认并修改。 +如果您发现 bug 请及时提 issue，我们会尽快确认并修改。 -wechat \ No newline at end of file +wechat