├── .github └── workflows │ ├── build.sh │ ├── build.yml │ └── contributor-tool ├── .gitignore ├── LANGS.md ├── book.json ├── cn ├── README.md ├── about-us.md ├── api-coding.md ├── api-config.md ├── api-dir.md ├── api-grammar.md ├── bloom.md ├── buiness-cache.md ├── business-coding.md ├── business-dev.md ├── ci-cd.md ├── coding-spec.md ├── component-center.md ├── concept-introduction.md ├── config-introduction.md ├── datacenter.md ├── dev-flow.md ├── dev-specification.md ├── doc-contibute.md ├── error-handle.md ├── error.md ├── executors.md ├── faq.md ├── framework-design.md ├── fx.md ├── go-queue.md ├── go-zero-design.md ├── go-zero-features.md ├── goctl-api.md ├── goctl-commands.md ├── goctl-install.md ├── goctl-model.md ├── goctl-other.md ├── goctl-plugin.md ├── goctl-rpc.md ├── goctl.md ├── golang-install.md ├── gomod-config.md ├── goreading.md ├── gotalk.md ├── intellij.md ├── join-us.md ├── jwt.md ├── learning-resource.md ├── log-collection.md ├── logx.md ├── micro-service.md ├── middleware.md ├── model-gen.md ├── monolithic-service.md ├── mysql.md ├── naming-spec.md ├── online-exchange.md ├── periodlimit.md ├── plugin-center.md ├── practise.md ├── prepare-other.md ├── prepare.md ├── project-dev.md ├── protoc-install.md ├── quick-start.md ├── redis-cache.md ├── redis-lock.md ├── resource │ ├── 3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png │ ├── 3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png │ ├── 76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png │ ├── 7715f4b6-8739-41ac-8c8c-04d187172e9d.png │ ├── 7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png │ ├── alert.png │ ├── api-compare.png │ ├── api-new.png │ ├── architechture.svg │ ├── author.jpeg │ ├── b97bf7df-1781-436e-bf04-f1dd90c60537.png │ ├── biz-redis-01.svg │ ├── biz-redis-02.svg │ ├── book.zip │ ├── c42c34e8d33d48ec8a63e56feeae882a.png │ ├── ci-cd.png │ ├── clone.png │ ├── compare.png │ ├── dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png │ ├── doc-edit.png │ ├── docker_env.png │ ├── f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png │ ├── fork.png │ ├── fx_log.png │ ├── gitlab-git-url.png │ ├── go-zero-logo.png │ ├── go-zero-practise.png │ ├── go_live_template.png │ ├── goctl-api-select.png │ ├── goctl-api.png │ ├── goctl-command.png │ ├── grafana-app.png │ ├── grafana-panel.png │ ├── grafana-qps.png │ ├── grafana.png │ ├── handler.gif │ ├── info.gif │ ├── intellij-model.png │ ├── jenkins-add-credentials.png │ ├── jenkins-build-with-parameters.png │ ├── jenkins-choice.png │ ├── jenkins-configure.png │ ├── jenkins-credentials-id.png │ ├── jenkins-credentials.png │ ├── jenkins-git.png │ ├── jenkins-new-item.png │ ├── json_tag.png │ ├── jump.gif │ ├── k8s-01.png │ ├── k8s-02.png │ ├── k8s-03.png │ ├── live_template.gif │ ├── log-flow.png │ ├── log.png │ ├── logo.png │ ├── new_pr.png │ ├── pipeline.png │ ├── pr_record.png │ ├── project_generate_code.png │ ├── prometheus-flow.png │ ├── prometheus-graph.webp │ ├── prometheus-start.png │ ├── psiTree.png │ ├── redis-cache-01.png │ ├── redis-cache-02.png │ ├── redis-cache-03.png │ ├── redis-cache-04.png │ ├── redis-cache-05.png │ ├── redis-cache-06.png │ ├── redis-cache-07.png │ ├── redis-cache-08.png │ ├── redis-cache-09.webp │ ├── redis-cache-10.png │ ├── redis-cache-11.webp │ ├── service.gif │ ├── service.png │ ├── ssh-add-key.png │ ├── type.gif │ └── user-pipeline-script.png ├── route-naming-spec.md ├── rpc-call.md ├── rpc-config.md ├── rpc-dir.md ├── service-deployment.md ├── service-design.md ├── service-monitor.md ├── source.md ├── stream.md ├── summary.md ├── template-cmd.md ├── template-manage.md ├── template.md ├── timing-wheel.md ├── tips.md ├── tokenlimit.md ├── tool-center.md ├── trace.md ├── vscode.md └── wechat.md ├── en ├── README.md ├── about-us.md ├── api-coding.md ├── api-config.md ├── api-dir.md ├── api-grammar.md ├── bloom.md ├── buiness-cache.md ├── business-coding.md ├── business-dev.md ├── ci-cd.md ├── coding-spec.md ├── component-center.md ├── concept-introduction.md ├── config-introduction.md ├── datacenter.md ├── dev-flow.md ├── dev-specification.md ├── doc-contibute.md ├── error-handle.md ├── error.md ├── executors.md ├── framework-design.md ├── fx.md ├── go-queue.md ├── go-zero-design.md ├── go-zero-features.md ├── goctl-api.md ├── goctl-commands.md ├── goctl-install.md ├── goctl-model.md ├── goctl-other.md ├── goctl-plugin.md ├── goctl-rpc.md ├── goctl.md ├── golang-install.md ├── gomod-config.md ├── goreading.md ├── gotalk.md ├── intellij.md ├── join-us.md ├── jwt.md ├── learning-resource.md ├── log-collection.md ├── logx.md ├── micro-service.md ├── middleware.md ├── model-gen.md ├── monolithic-service.md ├── mysql.md ├── naming-spec.md ├── online-exchange.md ├── periodlimit.md ├── plugin-center.md ├── practise.md ├── prepare-other.md ├── prepare.md ├── project-dev.md ├── protoc-install.md ├── quick-start.md ├── redis-cache.md ├── redis-lock.md ├── resource │ ├── 3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png │ ├── 3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png │ ├── 76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png │ ├── 7715f4b6-8739-41ac-8c8c-04d187172e9d.png │ ├── 7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png │ ├── alert.png │ ├── api-compare.png │ ├── api-new.png │ ├── architechture.svg │ ├── author.jpeg │ ├── b97bf7df-1781-436e-bf04-f1dd90c60537.png │ ├── biz-redis-01.svg │ ├── biz-redis-02.svg │ ├── book.zip │ ├── c42c34e8d33d48ec8a63e56feeae882a.png │ ├── ci-cd.png │ ├── clone.png │ ├── compare.png │ ├── dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png │ ├── doc-edit.png │ ├── docker_env.png │ ├── f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png │ ├── fork.png │ ├── fx_log.png │ ├── gitlab-git-url.png │ ├── go-zero-logo.png │ ├── go-zero-practise.png │ ├── go_live_template.png │ ├── goctl-api-select.png │ ├── goctl-api.png │ ├── goctl-command.png │ ├── grafana-app.png │ ├── grafana-panel.png │ ├── grafana-qps.png │ ├── grafana.png │ ├── handler.gif │ ├── info.gif │ ├── intellij-model.png │ ├── jenkins-add-credentials.png │ ├── jenkins-build-with-parameters.png │ ├── jenkins-choice.png │ ├── jenkins-configure.png │ ├── jenkins-credentials-id.png │ ├── jenkins-credentials.png │ ├── jenkins-git.png │ ├── jenkins-new-item.png │ ├── json_tag.png │ ├── jump.gif │ ├── k8s-01.png │ ├── k8s-02.png │ ├── k8s-03.png │ ├── live_template.gif │ ├── log-flow.png │ ├── log.png │ ├── logo.png │ ├── new_pr.png │ ├── pipeline.png │ ├── pr_record.png │ ├── project_generate_code.png │ ├── prometheus-flow.png │ ├── prometheus-graph.webp │ ├── prometheus-start.png │ ├── psiTree.png │ ├── redis-cache-01.png │ ├── redis-cache-02.png │ ├── redis-cache-03.png │ ├── redis-cache-04.png │ ├── redis-cache-05.png │ ├── redis-cache-06.png │ ├── redis-cache-07.png │ ├── redis-cache-08.png │ ├── redis-cache-09.webp │ ├── redis-cache-10.png │ ├── redis-cache-11.webp │ ├── service.gif │ ├── service.png │ ├── ssh-add-key.png │ ├── type.gif │ └── user-pipeline-script.png ├── route-naming-spec.md ├── rpc-call.md ├── rpc-config.md ├── rpc-dir.md ├── service-deployment.md ├── service-design.md ├── service-monitor.md ├── source.md ├── stream.md ├── summary.md ├── template-cmd.md ├── template-manage.md ├── template.md ├── timing-wheel.md ├── tokenlimit.md ├── tool-center.md ├── trace.md ├── vscode.md └── wechat.md ├── javascript └── gitalk.js └── readme.md /.github/workflows/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | ACCESSTOKEN=$1 3 | REPO="https://x-access-token:${ACCESSTOKEN}@github.com/zeromicro/go-zero-pages.git" 4 | 5 | # git 配置 6 | echo "git基础配置" 7 | git config --global user.name "anqiansong" 8 | git config --global user.email "anqiansong@tal.com" 9 | 10 | # push 11 | mkdir ./doc 12 | cd ./doc 13 | echo $PWD 14 | echo "document clone..." 15 | git clone ${REPO} 16 | cd go-zero-pages 17 | rm -rf ./* 18 | cp -rf ../../_book/* . 19 | git add ./* 20 | git commit -m 'update document' 21 | echo "document push..." 22 | git push -f -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | # 当master有代码提交或者有pr时，自动build gitbook，并覆盖git@github.com:zeromicro/go-zero.git仓库中内容 2 | # 以实现自动发布文档 3 | 4 | name: Document Build 5 | 6 | on: 7 | push: 8 | branches: [ master ] 9 | 10 | jobs: 11 | 12 | build: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - name: checkout code 16 | uses: actions/checkout@v2 17 | - name: chmod contributor tool 18 | run: chmod +x ./.github/workflows/contributor-tool 19 | - name: get latest contributors(cn) 20 | run: ./.github/workflows/contributor-tool -f contributor -l zh -o ./cn/contributor.md 21 | - name: get latest contributors(en) 22 | run: ./.github/workflows/contributor-tool -f contributor -l en -o ./en/contributor.md 23 | - name: append gitalk 24 | run: ./.github/workflows/contributor-tool -f comment 25 | - name: use node.js 26 | uses: actions/setup-node@v1 27 | with: 28 | node-version: '12.18.1' 29 | - name: install gitbook 30 | run: npm install gitbook-cli -g 31 | - name: gitbook version 32 | run: gitbook --version 33 | - name: gitbook install 34 | run: gitbook install 35 | - name: build 36 | run: gitbook build 37 | - name: delete original index 38 | run: rm -f ./_book/index.html 39 | - name: build index 40 | run: ./.github/workflows/contributor-tool -i ./_book/index.html 41 | - name: chmod 42 | run: chmod +x ./.github/workflows/build.sh 43 | - name: publish 44 | run: ./.github/workflows/build.sh ${{ secrets.ACCESSTOKEN }} 45 | shell: bash 46 | -------------------------------------------------------------------------------- /.github/workflows/contributor-tool: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/.github/workflows/contributor-tool -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.idea/ 2 | /_book/ 3 | /node_modules/ 4 | /cn/.DS_Store 5 | /cn/resource/Thumbs.db 6 | -------------------------------------------------------------------------------- /LANGS.md: -------------------------------------------------------------------------------- 1 | * [English](en) 2 | * [中文](cn) -------------------------------------------------------------------------------- /book.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "go-zero document", 3 | "author": "anqiansong", 4 | "description": "Golang 微服务框架 | 集成各种工程实践的 WEB 和 RPC 框架 | 一键生成 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 代码", 5 | "language": "zh-hans", 6 | "gitbook": "3.2.3", 7 | "plugins": [ 8 | "back-to-top-button", 9 | "chapter-fold", 10 | "code", 11 | "-lunr", 12 | "-search", 13 | "search-pro", 14 | "github", 15 | "splitter", 16 | "-sharing", 17 | "sharing-plus", 18 | "tbfed-pagefooter", 19 | "flexible-alerts", 20 | "page-toc-button", 21 | "pageview-count", 22 | "popup", 23 | "hide-element", 24 | "edit-link", 25 | "-highlight", 26 | "prism", 27 | "theme-comscore" 28 | ], 29 | "pluginsConfig": { 30 | "prism": { 31 | "lang": { 32 | "shell": "bash" 33 | }, 34 | "css": [ 35 | "prismjs/themes/prism-tomorrow.css" 36 | ] 37 | }, 38 | "github": { 39 | "url": "https://github.com/tal-tech/go-zero" 40 | }, 41 | "page-toc-button": { 42 | "maxTocDepth": 2, 43 | "minTocSize": 2 44 | }, 45 | "tbfed-pagefooter": { 46 | "copyright": "Copyright © 2019-2021 go-zero", 47 | "modify_label": "Last UpdateTime：", 48 | "modify_format": "YYYY-MM-DD HH:mm:ss" 49 | }, 50 | "hide-element": { 51 | "elements": [ 52 | ".gitbook-link" 53 | ] 54 | }, 55 | "edit-link": { 56 | "base": "https://github.com/zeromicro/go-zero-doc/blob/master", 57 | "label": "EDIT THIS PAGE" 58 | }, 59 | "sharing": { 60 | "douban": false, 61 | "facebook": false, 62 | "google": true, 63 | "hatenaBookmark": false, 64 | "instapaper": false, 65 | "line": true, 66 | "linkedin": true, 67 | "messenger": false, 68 | "pocket": false, 69 | "qq": false, 70 | "qzone": true, 71 | "stumbleupon": false, 72 | "twitter": false, 73 | "viber": false, 74 | "vk": false, 75 | "weibo": true, 76 | "whatsapp": false, 77 | "all": [ 78 | "douban", 79 | "facebook", 80 | "google", 81 | "linkedin", 82 | "twitter", 83 | "weibo", 84 | "qq", 85 | "qzone", 86 | "weibo" 87 | ] 88 | } 89 | } 90 | } 91 | -------------------------------------------------------------------------------- /cn/about-us.md: -------------------------------------------------------------------------------- 1 | # 关于我们 2 | 3 | ## go-zero 4 | go-zero 是一个集成了各种工程实践的 web 和 rpc 框架。通过弹性设计保障了大并发服务端的稳定性，经受了充分的实战检验。 5 | 6 | go-zero 包含极简的 API 定义和生成工具 goctl，可以根据定义的 api 文件一键生成 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 代码，并可直接运行。 7 | 8 | ## go-zero作者 9 | [kevwan](https://github.com/kevwan) 10 | 11 | **万俊峰**，晓黑板研发负责人，好未来技术委员会资深专家，拥有14年研发团队管理经验，16年架构设计经验，20年工程实战经验，负责过多个大型项目的架构设计，曾多次合伙创业（被收购），ArchSummit全球架构师峰会明星讲师，GopherChina大会金牌讲师，腾讯云开发者大会讲师。 12 | 13 | ## go-zero成员 14 | go-zero截止2021年4月，目前拥有30人的团队开发人员及60+的社区成员。 15 | 16 | ## go-zero社区 17 | 我们目前拥有4000多人的社区成员，在这里，你可以和大家讨论任何关于go-zero的技术，问题反馈，获取最新的go-zero信息，以及各位大佬每天分享的技术心得。 18 | 19 | ## go-zero社区群 20 | 社区群 21 | -------------------------------------------------------------------------------- /cn/api-coding.md: -------------------------------------------------------------------------------- 1 | # api文件编写 2 | 3 | ## 编写user.api文件 4 | ```shell 5 | $ vim service/user/cmd/api/user.api 6 | ``` 7 | ```text 8 | type ( 9 | LoginReq { 10 | Username string `json:"username"` 11 | Password string `json:"password"` 12 | } 13 | 14 | LoginReply { 15 | Id int64 `json:"id"` 16 | Name string `json:"name"` 17 | Gender string `json:"gender"` 18 | AccessToken string `json:"accessToken"` 19 | AccessExpire int64 `json:"accessExpire"` 20 | RefreshAfter int64 `json:"refreshAfter"` 21 | } 22 | ) 23 | 24 | service user-api { 25 | @handler login 26 | post /user/login (LoginReq) returns (LoginReply) 27 | } 28 | ``` 29 | ## 生成api服务 30 | ### 方式一 31 | 32 | ```shell 33 | $ cd book/service/user/cmd/api 34 | $ goctl api go -api user.api -dir . 35 | ``` 36 | ```text 37 | Done. 38 | ``` 39 | 40 | ### 方式二 41 | 42 | 在 `user.api` 文件右键，依次点击进入 `New`->`Go Zero`->`Api Code` ，进入目标目录选择，即api源码的目标存放目录，默认为user.api所在目录，选择好目录后点击OK即可。 43 | ![api生成](https://zeromicro.github.io/go-zero-pages/resource/goctl-api.png) 44 | ![api生成目录选择](https://zeromicro.github.io/go-zero-pages/resource/goctl-api-select.png) 45 | 46 | ### 方式三 47 | 48 | 打开user.api，进入编辑区,使用快捷键`Command+N`（for mac OS）或者 `alt+insert`（for windows），选择`Api Code`，同样进入目录选择弹窗，选择好目录后点击OK即可。 49 | 50 | # 猜你想看 51 | * [api语法](api-grammar.md) 52 | * [goctl api命令](goctl-api.md) 53 | * [api目录结构介绍](api-dir.md) -------------------------------------------------------------------------------- /cn/api-config.md: -------------------------------------------------------------------------------- 1 | # api配置 2 | api配置控制着api服务中的各种功能，包含但不限于服务监听地址，端口，环境配置，日志配置等，下面我们从一个简单的配置来看一下api中常用配置分别有什么作用。 3 | 4 | ## 配置说明 5 | 通过yaml配置我们会发现，有很多参数我们并没有于config对齐，这是因为config定义中，有很多都是带`optional`或者`default` 6 | 标签的，对于`optional`可选项，你可以根据自己需求判断是否需要设置，对于`default`标签，如果你觉得默认值就已经够了，可以不用设置， 7 | 一般`default`中的值基本不用修改，可以认为是最佳实践值。 8 | 9 | ### Config 10 | 11 | ```go 12 | type Config struct{ 13 | rest.RestConf // rest api配置 14 | Auth struct { // jwt鉴权配置 15 | AccessSecret string // jwt密钥 16 | AccessExpire int64 // 有效期，单位：秒 17 | } 18 | Mysql struct { // 数据库配置，除mysql外，可能还有mongo等其他数据库 19 | DataSource string // mysql链接地址，满足 $user:$password@tcp($ip:$port)/$db?$queries 格式即可 20 | } 21 | CacheRedis cache.CacheConf // redis缓存 22 | UserRpc zrpc.RpcClientConf // rpc client配置 23 | } 24 | ``` 25 | 26 | ### rest.RestConf 27 | api服务基础配置，包含监听地址，监听端口，证书配置，限流，熔断参数，超时参数等控制，对其展开我们可以看到： 28 | ```go 29 | service.ServiceConf // service配置 30 | Host string `json:",default=0.0.0.0"` // http监听ip，默认0.0.0.0 31 | Port int // http监听端口,必填 32 | CertFile string `json:",optional"` // https证书文件，可选 33 | KeyFile string `json:",optional"` // https私钥文件，可选 34 | Verbose bool `json:",optional"` // 是否打印详细http请求日志 35 | MaxConns int `json:",default=10000"` // http同时可接受最大请求数（限流数），默认10000 36 | MaxBytes int64 `json:",default=1048576,range=[0:8388608]"` // http可接受请求的最大ContentLength，默认1048576，被设置值不能必须在0到8388608之间 37 | // milliseconds 38 | Timeout int64 `json:",default=3000"` // 超时时长控制，单位：毫秒，默认3000 39 | CpuThreshold int64 `json:",default=900,range=[0:1000]"` // cpu降载阈值，默认900，可允许设置范围0到1000 40 | Signature SignatureConf `json:",optional"` // 签名配置 41 | ``` 42 | 43 | ### service.ServiceConf 44 | ```go 45 | type ServiceConf struct { 46 | Name string // 服务名称 47 | Log logx.LogConf // 日志配置 48 | Mode string `json:",default=pro,options=dev|test|pre|pro"` // 服务环境，dev-开发环境，test-测试环境，pre-预发环境，pro-正式环境 49 | MetricsUrl string `json:",optional"` // 指标上报接口地址，该地址需要支持post json即可 50 | Prometheus prometheus.Config `json:",optional"` // prometheus配置 51 | } 52 | ``` 53 | 54 | ### logx.LogConf 55 | ```go 56 | type LogConf struct { 57 | ServiceName string `json:",optional"` // 服务名称 58 | Mode string `json:",default=console,options=console|file|volume"` // 日志模式，console-输出到console，file-输出到当前服务器（容器）文件，，volume-输出docker挂在文件内 59 | Path string `json:",default=logs"` // 日志存储路径 60 | Level string `json:",default=info,options=info|error|severe"` // 日志级别 61 | Compress bool `json:",optional"` // 是否开启gzip压缩 62 | KeepDays int `json:",optional"` // 日志保留天数 63 | StackCooldownMillis int `json:",default=100"` // 日志write间隔 64 | } 65 | ``` 66 | 67 | ### prometheus.Config 68 | ```go 69 | type Config struct { 70 | Host string `json:",optional"` // prometheus 监听host 71 | Port int `json:",default=9101"` // prometheus 监听端口 72 | Path string `json:",default=/metrics"` // 上报地址 73 | } 74 | ``` 75 | 76 | ### SignatureConf 77 | ```go 78 | SignatureConf struct { 79 | Strict bool `json:",default=false"` // 是否Strict模式，如果是则PrivateKeys必填 80 | Expiry time.Duration `json:",default=1h"` // 有效期，默认1小时 81 | PrivateKeys []PrivateKeyConf // 签名密钥相关配置 82 | } 83 | ``` 84 | 85 | ### PrivateKeyConf 86 | ```go 87 | PrivateKeyConf struct { 88 | Fingerprint string // 指纹配置 89 | KeyFile string // 密钥配置 90 | } 91 | ``` 92 | 93 | ### cache.CacheConf 94 | ```go 95 | ClusterConf []NodeConf 96 | 97 | NodeConf struct { 98 | redis.RedisConf 99 | Weight int `json:",default=100"` // 权重 100 | } 101 | ``` 102 | 103 | ### redis.RedisConf 104 | ```go 105 | RedisConf struct { 106 | Host string // redis地址 107 | Type string `json:",default=node,options=node|cluster"` // redis类型 108 | Pass string `json:",optional"` // redis密码 109 | } 110 | ``` 111 | -------------------------------------------------------------------------------- /cn/api-dir.md: -------------------------------------------------------------------------------- 1 | # api目录介绍 2 | 3 | ```text 4 | . 5 | ├── etc 6 | │ └── greet-api.yaml // 配置文件 7 | ├── go.mod // mod文件 8 | ├── greet.api // api描述文件 9 | ├── greet.go // main函数入口 10 | └── internal 11 | ├── config 12 | │ └── config.go // 配置声明type 13 | ├── handler // 路由及handler转发 14 | │ ├── greethandler.go 15 | │ └── routes.go 16 | ├── logic // 业务逻辑 17 | │ └── greetlogic.go 18 | ├── middleware // 中间件文件 19 | │ └── greetmiddleware.go 20 | ├── svc // logic所依赖的资源池 21 | │ └── servicecontext.go 22 | └── types // request、response的struct，根据api自动生成，不建议编辑 23 | └── types.go 24 | ``` -------------------------------------------------------------------------------- /cn/bloom.md: -------------------------------------------------------------------------------- 1 | # bloom 2 | 3 | go-zero微服务框架中提供了许多开箱即用的工具，好的工具不仅能提升服务的性能而且还能提升代码的鲁棒性避免出错，实现代码风格的统一方便他人阅读等等，本系列文章将分别介绍go-zero框架中工具的使用及其实现原理 4 | 5 | ## 布隆过滤器[bloom](https://github.com/tal-tech/go-zero/blob/master/core/bloom/bloom.go) 6 | 在做服务器开发的时候，相信大家有听过布隆过滤器，可以判断某元素在不在集合里面,因为存在一定的误判和删除复杂问题,一般的使用场景是:防止缓存击穿(防止恶意攻击)、 垃圾邮箱过滤、cache digests 、模型检测器等、判断是否存在某行数据,用以减少对磁盘访问，提高服务的访问性能。     go-zero 提供的简单的缓存封装 bloom.bloom，简单使用方式如下 7 | 8 | ```go 9 | // 初始化 redisBitSet 10 | store := redis.NewRedis("redis 地址", redis.NodeType) 11 | // 声明一个bitSet, key="test_key"名且bits是1024位 12 | bitSet := newRedisBitSet(store, "test_key", 1024) 13 | // 判断第0位bit存不存在 14 | isSetBefore, err := bitSet.check([]uint{0}) 15 | 16 | // 对第512位设置为1 17 | err = bitSet.set([]uint{512}) 18 | // 3600秒后过期 19 | err = bitSet.expire(3600) 20 | 21 | // 删除该bitSet 22 | err = bitSet.del() 23 | ``` 24 | 25 | 26 | bloom 简单介绍了最基本的redis bitset 的使用。下面是真正的bloom实现。 27 | 对元素hash 定位 28 | 29 | ```go 30 | // 对元素进行hash 14次(const maps=14),每次都在元素后追加byte(0-13),然后进行hash. 31 | // 将locations[0-13] 进行取模,最终返回locations. 32 | func (f *BloomFilter) getLocations(data []byte) []uint { 33 | locations := make([]uint, maps) 34 | for i := uint(0); i < maps; i++ { 35 | hashValue := hash.Hash(append(data, byte(i))) 36 | locations[i] = uint(hashValue % uint64(f.bits)) 37 | } 38 | 39 | return locations 40 | } 41 | ``` 42 | 43 | 44 | 向bloom里面add 元素 45 | ```go 46 | // 我们可以发现 add方法使用了getLocations和bitSet的set方法。 47 | // 我们将元素进行hash成长度14的uint切片,然后进行set操作存到redis的bitSet里面。 48 | func (f *BloomFilter) Add(data []byte) error { 49 | locations := f.getLocations(data) 50 | err := f.bitSet.set(locations) 51 | if err != nil { 52 | return err 53 | } 54 | return nil 55 | } 56 | ``` 57 | 58 | 59 | 检查bloom里面是否有某元素 60 | ```go 61 | // 我们可以发现 Exists方法使用了getLocations和bitSet的check方法 62 | // 我们将元素进行hash成长度14的uint切片,然后进行bitSet的check验证,存在返回true,不存在或者check失败返回false 63 | func (f *BloomFilter) Exists(data []byte) (bool, error) { 64 | locations := f.getLocations(data) 65 | isSet, err := f.bitSet.check(locations) 66 | if err != nil { 67 | return false, err 68 | } 69 | if !isSet { 70 | return false, nil 71 | } 72 | 73 | return true, nil 74 | } 75 | ``` 76 | 77 | 本节主要介绍了go-zero框架中的 core.bloom 工具，在实际的项目中非常实用。用好工具对于提升服务性能和开发效率都有很大的帮助，希望本篇文章能给大家带来一些收获。 -------------------------------------------------------------------------------- /cn/buiness-cache.md: -------------------------------------------------------------------------------- 1 | # go-zero缓存设计之业务层缓存 2 | 3 | 在上一篇[go-zero缓存设计之持久层缓存](redis-cache.md)介绍了db层缓存，回顾一下，db层缓存主要设计可以总结为： 4 | 5 | * 缓存只删除不更新 6 | * 行记录始终只存储一份，即主键对应行记录 7 | * 唯一索引仅缓存主键值，不直接缓存行记录（参考mysql索引思想） 8 | * 防缓存穿透设计，默认一分钟 9 | * 不缓存多行记录 10 | 11 | ## 前言 12 | 13 | 在大型业务系统中，通过对持久层添加缓存，对于大多数单行记录查询，相信缓存能够帮持久层减轻很大的访问压力，但在实际业务中，数据读取不仅仅只是单行记录， 14 | 面对大量多行记录的查询，这对持久层也会造成不小的访问压力，除此之外，像秒杀系统、选课系统这种高并发的场景，单纯靠持久层的缓存是不现实的，本节我们来 介绍go-zero实践中的缓存设计——biz缓存。 15 | 16 | ## 适用场景举例 17 | 18 | * 选课系统 19 | * 内容社交系统 20 | * 秒杀 ... 21 | 22 | 像这些系统，我们可以在业务层再增加一层缓存来存储系统中的关键信息，如选课系统中学生选课信息，课程剩余名额；内容社交系统中某一段时间之间的内容信息等。 23 | 24 | 接下来，我们一内容社交系统来进行举例说明。 25 | 26 | 在内容社交系统中，我们一般是先查询一批内容列表，然后点击某条内容查看详情， 27 | 28 | 在没有添加biz缓存前，内容信息的查询流程图应该为： 29 | 30 | ![redis-cache-05](./resource/redis-cache-05.png) 31 | 32 | 从图以及上一篇文章[go-zero缓存设计之持久层缓存](redis-cache.md)中我们可以知道，内容列表的获取是没办法依赖缓存的， 33 | 如果我们在业务层添加一层缓存用来存储列表中的关键信息（甚至完整信息），那么多行记录的访问不在是一个问题，这就是biz redis要做的事情。 接下来我们来看一下设计方案，假设内容系统中单行记录包含以下字段 34 | 35 | |字段名称|字段类型|备注| 36 | |---|---|---| 37 | |id|string|内容id| 38 | |title|string|标题| 39 | |content|string|详细内容| 40 | |createTime|time.Time|创建时间| 41 | 42 | 我们的目标是获取一批内容列表，而尽量避免内容列表走db造成访问压力，首先我们采用redis的sort set数据结构来存储，根需要存储的字段信息量，有两种redis存储方案： 43 | 44 | * 缓存局部信息 45 | 46 | ![biz-redis-02](./resource/biz-redis-02.svg) 47 | 对其关键字段信息（如：id等）按照一定规则压缩，并存储，score我们用`createTime`毫秒值（时间值相等这里不讨论），这种存储方案的好处是节约redis存储空间， 48 | 那另一方面，缺点就是需要对列表详细内容进行二次回查（但这次回查是会利用到持久层的行记录缓存的） 49 | 50 | * 缓存完整信息 51 | 52 | ![biz-redis-01](./resource/biz-redis-01.svg) 53 | 对发布的所有内容按照一定规则压缩后均进行存储，同样score我们还是用`createTime`毫秒值，这种存储方案的好处是业务的增、删、查、改均走reids，而db层这时候 54 | 就可以不用考虑行记录缓存了，持久层仅提供数据备份和恢复使用，从另一方面来看，其缺点也很明显，需要的存储空间、配置要求更高，费用也会随之增大。 55 | 56 | 示例代码： 57 | ```golang 58 | type Content struct { 59 | Id string `json:"id"` 60 | Title string `json:"title"` 61 | Content string `json:"content"` 62 | CreateTime time.Time `json:"create_time"` 63 | } 64 | 65 | const bizContentCacheKey = `biz#content#cache` 66 | 67 | // AddContent 提供内容存储 68 | func AddContent(r redis.Redis, c *Content) error { 69 | v := compress(c) 70 | _, err := r.Zadd(bizContentCacheKey, c.CreateTime.UnixNano()/1e6, v) 71 | return err 72 | } 73 | 74 | // DelContent 提供内容删除 75 | func DelContent(r redis.Redis, c *Content) error { 76 | v := compress(c) 77 | _, err := r.Zrem(bizContentCacheKey, v) 78 | 79 | return err 80 | } 81 | 82 | // 内容压缩 83 | func compress(c *Content) string { 84 | // todo: do it yourself 85 | var ret string 86 | return ret 87 | } 88 | 89 | // 内容解压 90 | func unCompress(v string) *Content { 91 | // todo: do it yourself 92 | var ret Content 93 | return &ret 94 | } 95 | 96 | // ListByRangeTime提供根据时间段进行数据查询 97 | func ListByRangeTime(r redis.Redis, start, end time.Time) ([]*Content, error) { 98 | kvs, err := r.ZrangebyscoreWithScores(bizContentCacheKey, start.UnixNano()/1e6, end.UnixNano()/1e6) 99 | if err != nil { 100 | return nil, err 101 | } 102 | 103 | var list []*Content 104 | for _, kv := range kvs { 105 | data:=unCompress(kv.Key) 106 | list = append(list, data) 107 | } 108 | 109 | return list, nil 110 | } 111 | 112 | ``` 113 | 114 | 在以上例子中，redis是没有设置过期时间的，我们将增、删、改、查操作均同步到redis，我们认为内容社交系统的列表访问请求是比较高的情况下才做这样的方案设计， 115 | 除此之外，还有一些数据访问，没有想内容设计系统这么频繁的访问， 可能是某一时间段内访问量突如其来的增加，之后可能很长一段时间才会再访问一次，以此间隔， 116 | 或者说不会再访问了，面对这种场景，如果我又该如何考虑缓存的设计呢？在go-zero内容实践中，有两种方案可以解决这种问题： 117 | 118 | * 增加内存缓存：通过内存缓存来存储当前可能突发访问量比较大的数据，常用的存储方案采用map数据结构来存储，map数据存储实现比较简单，但缓存过期处理则需要增加 119 | 定时器来出来，另一宗方案是通过go-zero库中的 [Cache](https://github.com/tal-tech/go-zero/blob/master/core/collection/cache.go) ，其是专门 120 | 用于内存管理. 121 | * 采用biz redis,并设置合理的过期时间 122 | 123 | # 总结 124 | 以上两个场景可以包含大部分的多行记录缓存，对于多行记录查询量不大的场景，暂时没必要直接把biz redis放进去，可以先尝试让db来承担，开发人员可以根据持久层监控及服务 125 | 监控来衡量时候需要引入biz。 126 | -------------------------------------------------------------------------------- /cn/business-coding.md: -------------------------------------------------------------------------------- 1 | # 业务编码 2 | 前面一节，我们已经根据初步需求编写了user.api来描述user服务对外提供哪些服务访问，在本节我们接着前面的步伐， 3 | 通过业务编码来讲述go-zero怎么在实际业务中使用。 4 | 5 | ## 添加Mysql配置 6 | ```shell 7 | $ vim service/user/cmd/api/internal/config/config.go 8 | ``` 9 | ```go 10 | package config 11 | 12 | import "github.com/tal-tech/go-zero/rest" 13 | 14 | type Config struct { 15 | rest.RestConf 16 | Mysql struct{ 17 | DataSource string 18 | } 19 | 20 | CacheRedis cache.CacheConf 21 | } 22 | ``` 23 | 24 | ## 完善yaml配置 25 | ```shell 26 | $ vim service/user/cmd/api/etc/user-api.yaml 27 | ``` 28 | ```yaml 29 | Name: user-api 30 | Host: 0.0.0.0 31 | Port: 8888 32 | Mysql: 33 | DataSource: $user:$password@tcp($url)/$db?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai 34 | CacheRedis: 35 | - Host: $host 36 | Pass: $pass 37 | Type: node 38 | ``` 39 | 40 | > [!TIP] 41 | > $user: mysql数据库user 42 | > 43 | > $password: mysql数据库密码 44 | > 45 | > $url: mysql数据库连接地址 46 | > 47 | > $db: mysql数据库db名称，即user表所在database 48 | > 49 | > $host: redis连接地址 格式：ip:port，如:127.0.0.1:6379 50 | > 51 | > $pass: redis密码 52 | > 53 | > 更多配置信息，请参考[api配置介绍](api-config.md) 54 | 55 | ## 完善服务依赖 56 | ```shell 57 | $ vim service/user/cmd/api/internal/svc/servicecontext.go 58 | ``` 59 | ```go 60 | type ServiceContext struct { 61 | Config config.Config 62 | UserModel model.UserModel 63 | } 64 | 65 | func NewServiceContext(c config.Config) *ServiceContext { 66 | conn:=sqlx.NewMysql(c.Mysql.DataSource) 67 | return &ServiceContext{ 68 | Config: c, 69 | UserModel: model.NewUserModel(conn,c.CacheRedis), 70 | } 71 | } 72 | ``` 73 | ## 填充登录逻辑 74 | ```shell 75 | $ vim service/user/cmd/api/internal/logic/loginlogic.go 76 | ``` 77 | 78 | ```go 79 | func (l *LoginLogic) Login(req types.LoginReq) (*types.LoginReply, error) { 80 | if len(strings.TrimSpace(req.Username)) == 0 || len(strings.TrimSpace(req.Password)) == 0 { 81 | return nil, errors.New("参数错误") 82 | } 83 | 84 | userInfo, err := l.svcCtx.UserModel.FindOneByNumber(req.Username) 85 | switch err { 86 | case nil: 87 | case model.ErrNotFound: 88 | return nil, errors.New("用户名不存在") 89 | default: 90 | return nil, err 91 | } 92 | 93 | if userInfo.Password != req.Password { 94 | return nil, errors.New("用户密码不正确") 95 | } 96 | 97 | // ---start--- 98 | now := time.Now().Unix() 99 | accessExpire := l.svcCtx.Config.Auth.AccessExpire 100 | jwtToken, err := l.getJwtToken(l.svcCtx.Config.Auth.AccessSecret, now, l.svcCtx.Config.Auth.AccessExpire, userInfo.Id) 101 | if err != nil { 102 | return nil, err 103 | } 104 | // ---end--- 105 | 106 | return &types.LoginReply{ 107 | Id: userInfo.Id, 108 | Name: userInfo.Name, 109 | Gender: userInfo.Gender, 110 | AccessToken: jwtToken, 111 | AccessExpire: now + accessExpire, 112 | RefreshAfter: now + accessExpire/2, 113 | }, nil 114 | } 115 | ``` 116 | > [!TIP] 117 | > 上述代码中 [start]-[end]的代码实现见[jwt鉴权](jwt.md)章节 118 | 119 | # 猜你想看 120 | * [api语法](api-grammar.md) 121 | * [goctl api命令](goctl-api.md) 122 | * [api目录结构介绍](api-dir.md) 123 | * [jwt鉴权](jwt.md) 124 | * [api配置介绍](api-config.md) -------------------------------------------------------------------------------- /cn/business-dev.md: -------------------------------------------------------------------------------- 1 | # 业务开发 2 | 本章节我们用一个简单的示例去演示一下go-zero中的一些基本功能。本节将包含以下小节： 3 | * [目录拆分](service-design.md) 4 | * [model生成](model-gen.md) 5 | * [api文件编写](api-coding.md) 6 | * [业务编码](business-coding.md) 7 | * [jwt鉴权](jwt.md) 8 | * [中间件使用](middleware.md) 9 | * [rpc服务编写与调用](rpc-call.md) 10 | * [错误处理](error-handle.md) 11 | 12 | ## 演示工程下载 13 | 在正式进入后续文档叙述前，可以先留意一下这里的源码，后续我们会基于这份源码进行功能的递进式演示， 14 | 而不是完全从0开始，如果你从[快速入门](quick-start.md)章节过来，这份源码结构对你来说不是问题。 15 | 16 | 点击这里下载演示工程基础源码 17 | 18 | ## 演示工程说明 19 | 20 | ### 场景 21 | 程序员小明需要借阅一本《西游记》，在没有线上图书管理系统的时候，他每天都要去图书馆前台咨询图书馆管理员， 22 | * 小明：你好，请问今天《西游记》的图书还有吗？ 23 | * 管理员：没有了，明天再来看看吧。 24 | 25 | 过了一天，小明又来到图书馆，问： 26 | * 小明：你好，请问今天《西游记》的图书还有吗？ 27 | * 管理员：没有了，你过两天再来看看吧。 28 | 29 | 就这样经过多次反复，小明也是徒劳无功，浪费大量时间在来回的路上，于是终于忍受不了落后的图书管理系统， 30 | 他决定自己亲手做一个图书查阅系统。 31 | 32 | ### 预期实现目标 33 | * 用户登录 34 | 依靠现有学生系统数据进行登录 35 | * 图书检索 36 | 根据图书关键字搜索图书，查询图书剩余数量。 37 | 38 | ### 系统分析 39 | 40 | #### 服务拆分 41 | * user 42 | * api 提供用户登录协议 43 | * rpc 供search服务访问用户数据 44 | * search 45 | * api 提供图书查询协议 46 | 47 | > [!TIP] 48 | > 这个微小的图书借阅查询系统虽然小，从实际来讲不太符合业务场景，但是仅上面两个功能，已经满足我们对go-zero api/rpc的场景演示了， 49 | > 后续为了满足更丰富的go-zero功能演示，会在文档中进行业务插入即相关功能描述。这里仅用一个场景进行引入。 50 | > 51 | > 注意：user中的sql语句请自行创建到db中去，更多准备工作见[准备工作](prepare.md) 52 | > 53 | > 添加一些预设的用户数据到数据库，便于后面使用，为了篇幅，演示工程不对插入数据这种操作做详细演示。 54 | 55 | 56 | # 参考预设数据 57 | ```sql 58 | INSERT INTO `user` (number,name,password,gender)values ('666','小明','123456','男'); 59 | ``` -------------------------------------------------------------------------------- /cn/ci-cd.md: -------------------------------------------------------------------------------- 1 | # CI/CD 2 | > 在软件工程中，CI/CD或CICD通常指的是持续集成和持续交付或持续部署的组合实践。 3 | > ——引自[维基百科](https://zh.wikipedia.org/wiki/CI/CD) 4 | 5 | 6 | ![cd-cd](./resource/ci-cd.png) 7 | 8 | ## CI可以做什么？ 9 | 10 | > 现代应用开发的目标是让多位开发人员同时处理同一应用的不同功能。但是，如果企业安排在一天内将所有分支源代码合并在一起（称为“合并日”），最终可能造成工作繁琐、耗时，而且需要手动完成。这是因为当一位独立工作的开发人员对应用进行更改时，有可能会与其他开发人员同时进行的更改发生冲突。如果每个开发人员都自定义自己的本地集成开发环境（IDE），而不是让团队就一个基于云的 IDE 达成一致，那么就会让问题更加雪上加霜。 11 | 12 | > 持续集成（CI）可以帮助开发人员更加频繁地（有时甚至每天）将代码更改合并到共享分支或“主干”中。一旦开发人员对应用所做的更改被合并，系统就会通过自动构建应用并运行不同级别的自动化测试（通常是单元测试和集成测试）来验证这些更改，确保这些更改没有对应用造成破坏。这意味着测试内容涵盖了从类和函数到构成整个应用的不同模块。如果自动化测试发现新代码和现有代码之间存在冲突，CI 可以更加轻松地快速修复这些错误。 13 | 14 | > ——引自[《CI/CD是什么？如何理解持续集成、持续交付和持续部署》](https://www.redhat.com/zh/topics/devops/what-is-ci-cd) 15 | 16 | 从概念上来看，CI/CD包含部署过程，我们这里将部署(CD)单独放在一节[服务部署](service-deployment.md)， 17 | 本节就以gitlab来做简单的CI（Run Unit Test）演示。 18 | 19 | ## gitlab CI 20 | Gitlab CI/CD是Gitlab内置的软件开发工具，提供 21 | * 持续集成(CI) 22 | * 持续交付(CD) 23 | * 持续部署(CD) 24 | 25 | ## 准备工作 26 | * gitlab安装 27 | * git安装 28 | * gitlab runner安装 29 | 30 | ## 开启gitlab CI 31 | * 上传代码 32 | * 在gitlab新建一个仓库`go-zero-demo` 33 | * 将本地代码上传到`go-zero-demo`仓库 34 | * 在项目根目录下创建`.gitlab-ci.yaml`文件，通过此文件可以创建一个pipeline，其会在代码仓库中有内容变更时运行，pipeline由一个或多个按照顺序运行， 35 | 每个阶段可以包含一个或者多个并行运行的job。 36 | * 添加CI内容(仅供参考) 37 | 38 | ```yaml 39 | stages: 40 | - analysis 41 | 42 | analysis: 43 | stage: analysis 44 | image: golang 45 | script: 46 | - go version && go env 47 | - go test -short $(go list ./...) | grep -v "no test" 48 | ``` 49 | 50 | > [!TIP] 51 | > 以上CI为简单的演示，详细的gitlab CI请参考gitlab官方文档进行更丰富的CI集成。 52 | 53 | 54 | # 参考文档 55 | * [CI/CD 维基百科](https://zh.wikipedia.org/wiki/CI/CD) 56 | * [CI/CD是什么？如何理解持续集成、持续交付和持续部署](https://www.redhat.com/zh/topics/devops/what-is-ci-cd) 57 | * [Gitlab CI](https://docs.gitlab.com/ee/ci/) -------------------------------------------------------------------------------- /cn/coding-spec.md: -------------------------------------------------------------------------------- 1 | # 编码规范 2 | 3 | ## import 4 | * 单行import不建议用圆括号包裹 5 | * 按照`官方包`，NEW LINE，`当前工程包`，NEW LINE，`第三方依赖包`顺序引入 6 | ```go 7 | import ( 8 | "context" 9 | "string" 10 | 11 | "greet/user/internal/config" 12 | 13 | "google.golang.org/grpc" 14 | ) 15 | ``` 16 | 17 | ## 函数返回 18 | * 对象避免非指针返回 19 | * 遵循有正常值返回则一定无error，有error则一定无正常值返回的原则 20 | 21 | ## 错误处理 22 | * 有error必须处理，如果不能处理就必须抛出。 23 | * 避免下划线(_)接收error 24 | 25 | ## 函数体编码 26 | * 建议一个block结束空一行，如if、for等 27 | ```go 28 | func main (){ 29 | if x==1{ 30 | // do something 31 | } 32 | 33 | fmt.println("xxx") 34 | } 35 | ``` 36 | * return前空一行 37 | ```go 38 | func getUser(id string)(string,error){ 39 | .... 40 | 41 | return "xx",nil 42 | } 43 | ``` -------------------------------------------------------------------------------- /cn/component-center.md: -------------------------------------------------------------------------------- 1 | # 组件中心 2 | 组件中心会包括[go-zero](https://github.com/tal-tech/go-zero) core文件夹中的所有组件， 3 | 因此会比较庞大，而此资源将会持续更新，也欢迎大家来进行文档贡献，本节将包含以下目录（按照文档更新时间排序）： 4 | 5 | * [logx](logx.md) 6 | * [bloom](bloom.md) 7 | * [executors](executors.md) 8 | * [fx](fx.md) 9 | * [mysql](mysql.md) 10 | * [redis-lock](redis-lock.md) 11 | * [periodlimit](periodlimit.md) 12 | * [tokenlimit](tokenlimit.md) 13 | * [TimingWheel](timing-wheel.md) 14 | -------------------------------------------------------------------------------- /cn/concept-introduction.md: -------------------------------------------------------------------------------- 1 | # 概念介绍 2 | 3 | ## go-zero 4 | 晓黑板golang开源项目，集各种工程实践于一身的web和rpc框架。 5 | 6 | ## goctl 7 | 一个旨在为开发人员提高工程效率、降低出错率的辅助工具。 8 | 9 | ## goctl插件 10 | 指以goctl为中心的周边二进制资源，能够满足一些个性化的代码生成需求，如路由合并插件`goctl-go-compact`插件， 11 | 生成swagger文档的`goctl-swagger`插件，生成php调用端的`goctl-php`插件等。 12 | 13 | ## intellij/vscode插件 14 | 在intellij系列产品上配合goctl开发的插件，其将goctl命令行操作使用UI进行替代。 15 | 16 | ## api文件 17 | api文件是指用于定义和描述api服务的文本文件，其以.api后缀结尾，包含api语法描述内容。 18 | 19 | ## goctl环境 20 | goctl环境是使用goctl前的准备环境，包含 21 | * golang环境 22 | * protoc 23 | * protoc-gen-go插件 24 | * go module | gopath 25 | 26 | ## go-zero-demo 27 | go-zero-demo里面包含了文档中所有源码的一个大仓库，后续我们在编写演示demo时，我们均在此项目下创建子项目， 28 | 因此我们需要提前创建一个大仓库`go-zero-demo`，我这里把这个仓库放在home目录下。 29 | ```shell 30 | $ cd ~ 31 | $ mkdir go-zero-demo&&cd go-zero-demo 32 | $ go mod init go-zero-demo 33 | ``` 34 | 35 | 36 | # 参考文档 37 | * [go-zero](README.md) 38 | * [Goctl](goctl.md) 39 | * [插件中心](plugin-center.md) 40 | * [工具中心](tool-center.md) 41 | * [api语法](api-grammar.md) -------------------------------------------------------------------------------- /cn/config-introduction.md: -------------------------------------------------------------------------------- 1 | # 配置介绍 2 | 在正式使用go-zero之前，让我们先来了解一下go-zero中不同服务类型的配置定义，看看配置中每个字段分别有什么作用，本节将包含以下小节： 3 | * [api配置](api-config.md) 4 | * [rpc配置](rpc-config.md) -------------------------------------------------------------------------------- /cn/dev-flow.md: -------------------------------------------------------------------------------- 1 | # 开发流程 2 | 这里的开发流程和我们实际业务开发流程不是一个概念，这里的定义局限于go-zero的使用，即代码层面的开发细节。 3 | 4 | ## 开发流程 5 | * goctl环境准备[1] 6 | * 数据库设计 7 | * 业务开发 8 | * 新建工程 9 | * 创建服务目录 10 | * 创建服务类型（api/rpc/rmq/job/script） 11 | * 编写api、proto文件 12 | * 代码生成 13 | * 生成数据库访问层代码model 14 | * 配置config，yaml变更 15 | * 资源依赖填充（ServiceContext） 16 | * 添加中间件 17 | * 业务代码填充 18 | * 错误处理 19 | 20 | > [!TIP] 21 | > [1] [goctl环境](concept-introduction.md) 22 | 23 | ## 开发工具 24 | * Visual Studio Code 25 | * Goland(推荐) -------------------------------------------------------------------------------- /cn/dev-specification.md: -------------------------------------------------------------------------------- 1 | # 开发规范 2 | 在实际业务开发中，除了要提高业务开发效率，缩短业务开发周期，保证线上业务高性能，高可用的指标外，好的编程习惯也是一个开发人员基本素养之一，在本章节， 3 | 我们将介绍一下go-zero中的编码规范，本章节为可选章节，内容仅供交流与参考，本章节将从以下小节进行说明： 4 | * [命名规范](naming-spec.md) 5 | * [路由规范](route-naming-spec.md) 6 | * [编码规范](coding-spec.md) 7 | 8 | ## 开发三原则 9 | 10 | ### Clarity（清晰） 11 | 作者引用了`Hal Abelson and Gerald Sussman`的一句话： 12 | > Programs must be written for people to read, and only incidentally for machines to execute 13 | 14 | 程序是什么，程序必须是为了开发人员阅读而编写的，只是偶尔给机器去执行，99%的时间程序代码面向的是开发人员，而只有1%的时间可能是机器在执行，这里比例不是重点，从中我们可以看出，清晰的代码是多么的重要，因为所有程序，不仅是Go语言，都是由开发人员编写，供其他人阅读和维护。 15 | 16 | 17 | ### Simplicity（简单） 18 | > Simplicity is prerequisite for reliability 19 | 20 | `Edsger W. Dijkstra`认为：可靠的前提条件就是简单，我们在实际开发中都遇到过，这段代码在写什么，想要完成什么事情，开发人员不理解这段代码，因此也不知道如何去维护，这就带来了复杂性，程序越是复杂就越难维护，越难维护就会是程序变得越来越复杂，因此，遇到程序变复杂时首先应该想到的是——重构，重构会重新设计程序，让程序变得简单。 21 | 22 | ### Productivity（生产力） 23 | 在go-zero团队中，一直在强调这个话题，开发人员成产力的多少，并不是你写了多少行代码，完成了多少个模块开发，而是我们需要利用各种有效的途径来利用有限的时间完成开发效率最大化，而Goctl的诞生正是为了提高生产力， 24 | 因此这个开发原则我是非常认同的。 25 | 26 | -------------------------------------------------------------------------------- /cn/doc-contibute.md: -------------------------------------------------------------------------------- 1 | # 文档贡献 2 | 3 | ## 怎么贡献文档？ 4 | 点击顶部"编辑此页"按钮即可进入源码仓库对应的文件，开发人员将修改（添加）的文档通过pr形式提交， 5 | 我们收到pr后会进行文档审核，一旦审核通过即可更新文档。 6 | ![doc-edit](./resource/doc-edit.png) 7 | 8 | ## 可以贡献哪些文档？ 9 | * 文档编写错误 10 | * 文档不规范、不完整 11 | * go-zero应用实践、心得 12 | * 组件中心 13 | 14 | ## 文档pr通过后文档多久会更新？ 15 | 在pr接受后，github action会自动build gitbook并发布，因此在github action成功后1-2分钟即可查看更新后的文档。 16 | 17 | ## 文档贡献注意事项 18 | * 纠错、完善源文档可以直接编写原来的md文件 19 | * 新增组件文档需要保证文档排版、易读，且组件文档需要放在[组件中心](component-center.md)子目录中 20 | * go-zero应用实践分享可以直接放在[开发实践](practise.md)子目录下 21 | 22 | ## 目录结构规范 23 | * 目录结构不宜过深，最好不要超过3层 24 | * 组件文档需要在归属到[组件中心](component-center.md)，如 25 | ```markdown 26 | * [开发实践](practise.md) 27 | * [logx](logx.md) 28 | * [bloom](bloom.md) 29 | * [executors](executors.md) 30 | * 你的文档目录名称 31 | ``` 32 | * 应用实践需要归属到[开发实践](practise.md)，如 33 | ```markdown 34 | * [开发实践](practise.md) 35 | * [我是如何用go-zero 实现一个中台系统](datacenter.md) 36 | * [流数据处理利器](stream.md) 37 | * [10月3日线上交流问题汇总](online-exchange.md 38 | * 你的文档目录名称 39 | ``` 40 | 41 | ## 开发实践文档模板 42 | ```markdown 43 | # 标题 44 | 45 | > 作者：填入作者名称 46 | > 47 | > 原文连接： 原文连接 48 | 49 | some markdown content 50 | ``` 51 | 52 | # 猜你想看 53 | * [怎么参与贡献](join-us.md) 54 | * [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) 55 | 56 | -------------------------------------------------------------------------------- /cn/error.md: -------------------------------------------------------------------------------- 1 | # 常见错误处理 2 | 3 | ## Windows上报错 4 | ```text 5 | A required privilege is not held by the client. 6 | ``` 7 | 解决方法："以管理员身份运行" goctl 即可。 8 | 9 | ## grpc引起错误 10 | * 错误一 11 | ```text 12 | protoc-gen-go: unable to determine Go import path for "greet.proto" 13 | 14 | Please specify either: 15 | • a "go_package" option in the .proto source file, or 16 | • a "M" argument on the command line. 17 | 18 | See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information. 19 | 20 | --go_out: protoc-gen-go: Plugin failed with status code 1. 21 | 22 | ``` 23 | 解决方法： 24 | ```text 25 | go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2 26 | ``` 27 | 28 | ## protoc-gen-go安装失败 29 | ```text 30 | go get github.com/golang/protobuf/protoc-gen-go: module github.com/golang/protobuf/protoc-gen-go: Get "https://proxy.golang.org/github.com/golang/protobuf/protoc-gen-go/@v/list": dial tcp 216.58.200.49:443: i/o timeout 31 | ``` 32 | 33 | 请确认`GOPROXY`已经设置,GOPROXY设置见[go module配置](gomod-config.md) 34 | 35 | ## api服务启动失败 36 | ```text 37 | error: config file etc/user-api.yaml, error: type mismatch for field xx 38 | ``` 39 | 40 | 请确认`user-api.yaml`配置文件中配置项是否已经配置，如果有值，检查一下yaml配置文件是否符合yaml格式。 41 | 42 | ## goctl找不到 43 | ``` 44 | command not found: goctl 45 | ``` 46 | 请确保goctl已经安装或者goctl是否已经添加到环境变量 -------------------------------------------------------------------------------- /cn/faq.md: -------------------------------------------------------------------------------- 1 | # 常见问题集合 2 | 3 | 1. goctl安装了执行命令却提示 `command not found: goctl` 字样。 4 | > 如果你通过 `go get` 方式安装，那么 `goctl` 应该位于 `$GOPATH` 中， 5 | > 你可以通过 `go env GOPATH` 查看完整路径，不管你的 `goctl` 是在 `$GOPATH`中， 6 | > 还是在其他目录，出现上述问题的原因就是 `goctl` 所在目录不在 `PATH` (环境变量)中所致。 7 | 8 | 2. rpc怎么调用 9 | > 该问题可以参考快速开始中的[rpc编写与调用](rpc-call.md)介绍，其中有rpc调用的使用逻辑。 10 | 11 | 3. proto使用了import，goctl命令需要怎么写。 12 | > `goctl` 对于import的proto指定 `BasePath` 提供了 `protoc` 的flag映射，即 `--proto_path, -I`， 13 | > `goctl` 会将此flag值传递给 `protoc`. 14 | 15 | 4. 假设 `base.proto` 的被main proto 引入了，为什么不生能生成`base.pb.go`。 16 | > 对于 `base.proto` 这种类型的文件，一般都是开发者有message复用的需求，他的来源不止有开发者自己编写的`proto`文件， 17 | > 还有可能来源于 `google.golang.org/grpc` 中提供的一些基本的proto,比如 `google/protobuf/any.proto`, 如果由 `goctl` 18 | > 来生成，那么就失去了集中管理这些proto的意义。 19 | 20 | 5. model怎么控制缓存时间 21 | > 在 `sqlc.NewNodeConn` 的时候可以通过可选参数 `cache.WithExpiry` 传递，如缓存时间控制为1天，代码如下: 22 | > ```go 23 | > sqlc.NewNodeConn(conn,redis,cache.WithExpiry(24*time.Hour)) 24 | > ``` 25 | 26 | 6. jwt鉴权怎么实现 27 | > 请参考[jwt鉴权](jwt.md) 28 | 29 | 7. api中间件怎么使用 30 | > 请参考[中间件](middleware.md) 31 | 32 | 8. 怎么关闭输出的统计日志(stat)？ 33 | > logx.DisableStat() 34 | 35 | 9. rpc直连与服务发现连接模式写法 36 | ```go 37 | // mode1: 集群直连 38 | // conf:=zrpc.NewDirectClientConf([]string{"ip:port"},"app","token") 39 | 40 | // mode2: etcd 服务发现 41 | // conf:=zrpc.NewEtcdClientConf([]string{"ip:port"},"key","app","token") 42 | // client, _ := zrpc.NewClient(conf) 43 | 44 | // mode3: ip直连mode 45 | // client, _ := zrpc.NewClientWithTarget("127.0.0.1:8888") 46 | ``` 47 | 48 | faq会不定期更新大家遇到的问题，也欢迎大家把常见问题通过pr写在这里。 49 | -------------------------------------------------------------------------------- /cn/framework-design.md: -------------------------------------------------------------------------------- 1 | # 框架设计 2 | 3 | ![整体框架](./resource/architechture.svg) 4 | 5 | 本节将从 go-zero 的设计理念，go-zero 服务的最佳实践目录来说明 go-zero 框架的设计，本节将包含以下小节： 6 | 7 | * [go-zero设计理念](go-zero-design.md) 8 | * [go-zero特点](go-zero-features.md) 9 | * [api语法介绍](api-grammar.md) 10 | * [api目录结构](api-dir.md) 11 | * [rpc目录结构](rpc-dir.md) 12 | -------------------------------------------------------------------------------- /cn/go-zero-design.md: -------------------------------------------------------------------------------- 1 | # go-zero设计理念 2 | 3 | 对于微服务框架的设计，我们期望保障微服务稳定性的同时，也要特别注重研发效率。所以设计之初，我们就有如下一些准则： 4 | 5 | * 保持简单，第一原则 6 | * 弹性设计，面向故障编程 7 | * 工具大于约定和文档 8 | * 高可用 9 | * 高并发 10 | * 易扩展 11 | * 对业务开发友好，封装复杂度 12 | * 约束做一件事只有一种方式 -------------------------------------------------------------------------------- /cn/go-zero-features.md: -------------------------------------------------------------------------------- 1 | # go-zero特性 2 | 3 | go-zero 是一个集成了各种工程实践的包含 web 和 rpc 框架，有如下主要特点： 4 | 5 | * 强大的工具支持，尽可能少的代码编写 6 | * 极简的接口 7 | * 完全兼容 net/http 8 | * 支持中间件，方便扩展 9 | * 高性能 10 | * 面向故障编程，弹性设计 11 | * 内建服务发现、负载均衡 12 | * 内建限流、熔断、降载，且自动触发，自动恢复 13 | * API 参数自动校验 14 | * 超时级联控制 15 | * 自动缓存控制 16 | * 链路跟踪、统计报警等 17 | * 高并发支撑，稳定保障了疫情期间每天的流量洪峰 18 | 19 | 如下图，我们从多个层面保障了整体服务的高可用： 20 | 21 | ![弹性设计](https://gitee.com/kevwan/static/raw/master/doc/images/resilience.jpg) -------------------------------------------------------------------------------- /cn/goctl-api.md: -------------------------------------------------------------------------------- 1 | # api命令 2 | goctl api是goctl中的核心模块之一，其可以通过.api文件一键快速生成一个api服务，如果仅仅是启动一个go-zero的api演示项目， 3 | 你甚至都不用编码，就可以完成一个api服务开发及正常运行。在传统的api项目中，我们要创建各级目录，编写结构体， 4 | 定义路由，添加logic文件，这一系列操作，如果按照一条协议的业务需求计算，整个编码下来大概需要5～6分钟才能真正进入业务逻辑的编写， 5 | 这还不考虑编写过程中可能产生的各种错误，而随着服务的增多，随着协议的增多，这部分准备工作的时间将成正比上升， 6 | 而goctl api则可以完全替代你去做这一部分工作，不管你的协议要定多少个，最终来说，只需要花费10秒不到即可完成。 7 | 8 | > [!TIP] 9 | > 其中的结构体编写，路由定义用api进行替代，因此总的来说，省去的是你创建文件夹、添加各种文件及资源依赖的过程的时间。 10 | 11 | ## api命令说明 12 | ```shell 13 | $ goctl api -h 14 | ``` 15 | ```text 16 | NAME: 17 | goctl api - generate api related files 18 | 19 | USAGE: 20 | goctl api command [command options] [arguments...] 21 | 22 | COMMANDS: 23 | new fast create api service 24 | format format api files 25 | validate validate api file 26 | doc generate doc files 27 | go generate go files for provided api in yaml file 28 | java generate java files for provided api in api file 29 | ts generate ts files for provided api in api file 30 | dart generate dart files for provided api in api file 31 | kt generate kotlin code for provided api file 32 | plugin custom file generator 33 | 34 | OPTIONS: 35 | -o value the output api file 36 | --help, -h show help 37 | ``` 38 | 39 | 从上文中可以看到，根据功能的不同，api包含了很多的自命令和flag，我们这里重点说明一下 40 | `go`子命令，其功能是生成golang api服务，我们通过`goctl api go -h`看一下使用帮助： 41 | ```shell 42 | $ goctl api go -h 43 | ``` 44 | ```text 45 | NAME: 46 | goctl api go - generate go files for provided api in yaml file 47 | 48 | USAGE: 49 | goctl api go [command options] [arguments...] 50 | 51 | OPTIONS: 52 | --dir value the target dir 53 | --api value the api file 54 | --style value the file naming format, see [https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/readme.md] 55 | ``` 56 | 57 | * --dir 代码输出目录 58 | * --api 指定api源文件 59 | * --style 指定生成代码文件的文件名称风格，详情见[文件名称命名style说明](https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/readme.md) 60 | 61 | ## 使用示例 62 | ```shell 63 | $ goctl api go -api user.api -dir . -style gozero 64 | ``` 65 | 66 | 67 | # 猜你想看 68 | * [api语法](api-grammar.md) 69 | * [api目录](api-dir.md) -------------------------------------------------------------------------------- /cn/goctl-install.md: -------------------------------------------------------------------------------- 1 | # Goctl安装 2 | 3 | ## 前言 4 | Goctl在go-zero项目开发着有着很大的作用，其可以有效的帮助开发者大大提高开发效率，减少代码的出错率，缩短业务开发的工作量，更多的Goctl的介绍请阅读[Goctl介绍](goctl.md), 5 | 在这里我们强烈推荐大家安装，因为后续演示例子中我们大部分都会以goctl进行演示。 6 | 7 | ## 安装(mac&linux) 8 | * download&install 9 | ```shell 10 | GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl 11 | ``` 12 | * 环境变量检测 13 | 14 | `go get`下载编译后的二进制文件位于`$GOPATH/bin`目录下，要确保`$GOPATH/bin`已经添加到环境变量。 15 | ```shell 16 | $ sudo vim /etc/paths 17 | ``` 18 | 在最后一行添加如下内容 19 | ```text 20 | $GOPATH/bin 21 | ``` 22 | > [!TIP] 23 | > `$GOPATH`为你本机上的文件地址 24 | 25 | * 安装结果验证 26 | ```shell 27 | $ goctl -v 28 | ``` 29 | ```text 30 | goctl version 1.1.4 darwin/amd64 31 | ``` 32 | 33 | > [!TIP] 34 | > windows用户添加环境变量请自行google 35 | -------------------------------------------------------------------------------- /cn/goctl-plugin.md: -------------------------------------------------------------------------------- 1 | # plugin命令 2 | 3 | goctl支持针对api自定义插件，那我怎么来自定义一个插件了？来看看下面最终怎么使用的一个例子。 4 | ```go 5 | $ goctl api plugin -p goctl-android="android -package com.tal" -api user.api -dir . 6 | ``` 7 | 8 | 上面这个命令可以分解成如下几步： 9 | * goctl 解析api文件 10 | * goctl 将解析后的结构 ApiSpec 和参数传递给goctl-android可执行文件 11 | * goctl-android 根据 ApiSpec 结构体自定义生成逻辑。 12 | 13 | 此命令前面部分 goctl api plugin -p 是固定参数，goctl-android="android -package com.tal" 是plugin参数，其中goctl-android是插件二进制文件，android -package com.tal是插件的自定义参数，-api user.api -dir .是goctl通用自定义参数。 14 | ## 怎么编写自定义插件？ 15 | go-zero框架中包含了一个很简单的自定义插件 demo，代码如下： 16 | ```go 17 | package main 18 | 19 | import ( 20 | "fmt" 21 | 22 | "github.com/tal-tech/go-zero/tools/goctl/plugin" 23 | ) 24 | 25 | func main() { 26 | plugin, err := plugin.NewPlugin() 27 | if err != nil { 28 | panic(err) 29 | } 30 | if plugin.Api != nil { 31 | fmt.Printf("api: %+v \n", plugin.Api) 32 | } 33 | fmt.Printf("dir: %s \n", plugin.Dir) 34 | fmt.Println("Enjoy anything you want.") 35 | } 36 | ``` 37 | 38 | `plugin, err := plugin.NewPlugin()` 这行代码作用是解析从goctl传递过来的数据，里面包含如下部分内容： 39 | 40 | ```go 41 | type Plugin struct { 42 | Api *spec.ApiSpec 43 | Style string 44 | Dir string 45 | } 46 | ``` 47 | > [!TIP] 48 | > Api：定义了api文件的结构数据 49 | > 50 | > Style：可选参数，可以用来控制文件命名规范 51 | > 52 | > Dir：工作目录 53 | 54 | 55 | 完整的基于plugin实现的android plugin演示项目 56 | [https://github.com/zeromicro/goctl-android](https://github.com/zeromicro/goctl-android) 57 | 58 | # 猜你想看 59 | * [api目录](api-dir.md) 60 | * [api语法](api-grammar.md) 61 | * [api配置](api-config.md) 62 | * [api命令介绍](goctl-api.md) -------------------------------------------------------------------------------- /cn/goctl.md: -------------------------------------------------------------------------------- 1 | # Goctl 2 | 3 | goctl是go-zero微服务框架下的代码生成工具。使用 goctl 可显著提升开发效率，让开发人员将时间重点放在业务开发上，其功能有： 4 | 5 | - api服务生成 6 | - rpc服务生成 7 | - model代码生成 8 | - 模板管理 9 | 10 | 本节将包含以下内容： 11 | 12 | * [命令大全](goctl-commands.md) 13 | * [api命令](goctl-api.md) 14 | * [rpc命令](goctl-rpc.md) 15 | * [model命令](goctl-model.md) 16 | * [plugin命令](goctl-plugin.md) 17 | * [其他命令](goctl-other.md) 18 | 19 | ## goctl 读音 20 | 很多人会把 `goctl` 读作 `go-C-T-L`，这种是错误的念法，应参照 `go control` 读做 `ɡō kənˈtrōl`。 21 | 22 | ## 查看版本信息 23 | ```shell 24 | $ goctl -v 25 | ``` 26 | 27 | 如果安装了goctl则会输出以下格式的文本信息： 28 | 29 | ```text 30 | goctl version ${version} ${os}/${arch} 31 | ``` 32 | 33 | 例如输出： 34 | ```text 35 | goctl version 1.2.2 darwin/amd64 36 | ``` 37 | 38 | 版本号说明 39 | * version：goctl 版本号 40 | * os：当前操作系统名称 41 | * arch： 当前系统架构名称 42 | 43 | ## 安装 goctl 44 | 45 | ### 方式一（go get） 46 | 47 | ```shell 48 | $ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl 49 | ``` 50 | 51 | 通过此命令可以将goctl工具安装到 `$GOPATH/bin` 目录下 52 | 53 | ### 方式二 （fork and build） 54 | 55 | 从 go-zero代码仓库 `git@github.com:tal-tech/go-zero.git` 拉取一份源码，进入 `tools/goctl/`目录下编译一下 goctl 文件，然后将其添加到环境变量中。 56 | 57 | 安装完成后执行`goctl -v`，如果输出版本信息则代表安装成功，例如： 58 | 59 | ```shell 60 | $ goctl -v 61 | 62 | goctl version 1.2.2 darwin/amd64 63 | ``` 64 | 65 | ## 常见问题 66 | ``` 67 | command not found: goctl 68 | ``` 69 | 请确保goctl已经安装，或者goctl是否已经正确添加到当前shell的环境变量中。 70 | -------------------------------------------------------------------------------- /cn/golang-install.md: -------------------------------------------------------------------------------- 1 | # Golang环境安装 2 | 3 | ## 前言 4 | 开发golang程序，必然少不了对其环境的安装，我们这里选择以1.15.1为例。 5 | 6 | ## 官方文档 7 | [https://golang.google.cn/doc/install](https://golang.google.cn/doc/install) 8 | 9 | ## mac OS安装Go 10 | 11 | * 下载并安装[Go for Mac](https://dl.google.com/go/go1.15.1.darwin-amd64.pkg) 12 | * 验证安装结果 13 | ```shell 14 | $ go version 15 | ``` 16 | ```text 17 | go version go1.15.1 darwin/amd64 18 | ``` 19 | ## linux 安装Go 20 | * 下载[Go for Linux](https://golang.org/dl/go1.15.8.linux-amd64.tar.gz) 21 | * 解压压缩包至`/usr/local` 22 | ```shell 23 | $ tar -C /usr/local -xzf go1.15.8.linux-amd64.tar.gz 24 | ``` 25 | * 添加`/usr/local/go/bin`到环境变量 26 | ```shell 27 | $ $HOME/.profile 28 | ``` 29 | ```shell 30 | export PATH=$PATH:/usr/local/go/bin 31 | ``` 32 | ```shell 33 | $ source $HOME/.profile 34 | ``` 35 | * 验证安装结果 36 | ```shell 37 | $ go version 38 | ``` 39 | ```text 40 | go version go1.15.1 linux/amd64 41 | ``` 42 | ## Windows安装Go 43 | * 下载并安装[Go for Windows](https://golang.org/dl/go1.15.8.windows-amd64.msi) 44 | * 验证安装结果 45 | ```shell 46 | $ go version 47 | ``` 48 | ```text 49 | go version go1.15.1 windows/amd64 50 | ``` 51 | 52 | ## 其他 53 | 更多操作系统安装见[https://golang.org/dl/](https://golang.org/dl/) 54 | -------------------------------------------------------------------------------- /cn/gomod-config.md: -------------------------------------------------------------------------------- 1 | # Go Module设置 2 | 3 | ## Go Module介绍 4 | > Modules are how Go manages dependencies.[1] 5 | 6 | 即Go Module是Golang管理依赖性的方式，像Java中的Maven，Android中的Gradle类似。 7 | 8 | ## MODULE配置 9 | * 查看`GO111MODULE`开启情况 10 | ```shell 11 | $ go env GO111MODULE 12 | ``` 13 | ```text 14 | on 15 | ``` 16 | * 开启`GO111MODULE`，如果已开启（即执行`go env GO111MODULE`结果为`on`）请跳过。 17 | ```shell 18 | $ go env -w GO111MODULE="on" 19 | ``` 20 | * 设置GOPROXY 21 | ```shell 22 | $ go env -w GOPROXY=https://goproxy.cn 23 | ``` 24 | * 设置GOMODCACHE 25 | 26 | 查看GOMODCACHE 27 | ```shell 28 | $ go env GOMODCACHE 29 | ``` 30 | 如果目录不为空或者`/dev/null`，请跳过。 31 | ```shell 32 | go env -w GOMODCACHE=$GOPATH/pkg/mod 33 | ``` 34 | 35 | 36 | # 参考文档 37 | [1] [Go Modules Reference](https://golang.google.cn/ref/mod) -------------------------------------------------------------------------------- /cn/goreading.md: -------------------------------------------------------------------------------- 1 | # Go夜读 2 | 3 | * [2020-08-16 晓黑板 go-zero 微服务框架的架构设计](https://talkgo.org/t/topic/729) 4 | * [2020-10-03 go-zero 微服务框架和线上交流](https://talkgo.org/t/topic/1070) 5 | * [防止缓存击穿之进程内共享调用](https://talkgo.org/t/topic/968) 6 | * [基于go-zero实现JWT认证](https://talkgo.org/t/topic/1114) 7 | * [再见go-micro！企业项目迁移go-zero全攻略（一）](https://talkgo.org/t/topic/1607) -------------------------------------------------------------------------------- /cn/gotalk.md: -------------------------------------------------------------------------------- 1 | # Go开源说 2 | 3 | * [Go 开源说第四期 - Go-Zero](https://www.bilibili.com/video/BV1Jy4y127Xu) -------------------------------------------------------------------------------- /cn/intellij.md: -------------------------------------------------------------------------------- 1 | # intellij插件 2 | 3 | ## Go-Zero Plugin 4 | 5 | [go-zero](https://github.com/tal-tech/go-zero) 6 | [license](https://github.com/zeromicro/goctl-intellij/blob/main/LICENSE) 7 | [release](https://github.com/zeromicro/goctl-intellij/releases) 8 | [Java CI with Gradle](https://github.com/zeromicro/goctl-intellij/actions) 9 | 10 | ## 介绍 11 | 一款支持go-zero api语言结构语法高亮、检测以及api、rpc、model快捷生成的插件工具。 12 | 13 | 14 | ## idea版本要求 15 | * IntelliJ 2019.3+ (Ultimate or Community) 16 | * Goland 2019.3+ 17 | * WebStorm 2019.3+ 18 | * PhpStorm 2019.3+ 19 | * PyCharm 2019.3+ 20 | * RubyMine 2019.3+ 21 | * CLion 2019.3+ 22 | 23 | ## 版本特性 24 | * api语法高亮 25 | * api语法、语义检测 26 | * struct、route、handler重复定义检测 27 | * type跳转到类型声明位置 28 | * 上下文菜单中支持api、rpc、mode相关menu选项 29 | * 代码格式化(option+command+L) 30 | * 代码提示 31 | 32 | ## 安装方式 33 | 34 | ### 方式一 35 | 在github的release中找到最新的zip包，下载本地安装即可。（无需解压） 36 | 37 | ### 方式二 38 | 在plugin商店中，搜索`Goctl`安装即可 39 | 40 | 41 | ## 预览 42 | ![preview](./resource/api-compare.png) 43 | 44 | ## 新建 Api(Proto) file 45 | 在工程区域目标文件夹`右键->New-> New Api(Proto) File ->Empty File/Api(Proto) Template`,如图： 46 | ![preview](./resource/api-new.png) 47 | 48 | # 快速生成api/rpc服务 49 | 在目标文件夹`右键->New->Go Zero -> Api Greet Service/Rpc Greet Service` 50 | 51 | ![preview](./resource/service.png) 52 | 53 | # Api/Rpc/Model Code生成 54 | 55 | ## 方法一(工程区域) 56 | 57 | 对应文件（api、proto、sql）`右键->New->Go Zero-> Api/Rpc/Model Code`,如图： 58 | 59 | ![preview](./resource/project_generate_code.png) 60 | 61 | ## 方法二（编辑区域） 62 | 对应文件（api、proto、sql）`右键-> Generate-> Api/Rpc/Model Code` 63 | 64 | 65 | # 错误提示 66 | ![context menu](./resource/alert.png) 67 | 68 | 69 | # Live Template 70 | Live Template可以加快我们对api文件的编写，比如我们在go文件中输入`main`关键字根据tip回车后会插入一段模板代码 71 | ```go 72 | func main(){ 73 | 74 | } 75 | ``` 76 | 或者说看到下图你会更加熟悉，曾几何时你还在这里定义过template 77 | ![context menu](./resource/go_live_template.png) 78 | 79 | 下面就进入今天api语法中的模板使用说明吧，我们先来看看service模板的效果 80 | ![context menu](./resource/live_template.gif) 81 | 82 | 首先上一张图了解一下api文件中几个模板生效区域（psiTree元素区域） 83 | ![context menu](./resource/psiTree.png) 84 | 85 | #### 预设模板及生效区域 86 | | 模板关键字 | psiTree生效区域 |描述 87 | | ---- | ---- | ---- | 88 | | @doc | ApiService |doc注释模板| 89 | | doc | ApiService |doc注释模板| 90 | | struct | Struct |struct声明模板| 91 | | info | ApiFile |info block模板| 92 | | type | ApiFile |type group模板| 93 | | handler | ApiService |handler文件名模板| 94 | | get | ApiService |get方法路由模板| 95 | | head | ApiService |head方法路由模板| 96 | | post | ApiService |post方法路由模板| 97 | | put | ApiService |put方法路由模板| 98 | | delete | ApiService |delete方法路由模板| 99 | | connect | ApiService |connect方法路由模板| 100 | | options | ApiService |options方法路由模板| 101 | | trace | ApiService |trace方法路由模板| 102 | | service | ApiFile |service服务block模板| 103 | | json | Tag、Tag literal |tag模板| 104 | | xml | Tag、Tag literal |tag模板| 105 | | path | Tag、Tag literal |tag模板| 106 | | form | Tag、Tag literal |tag模板| 107 | 108 | 关于每个模板对应内容可在`Goland(mac Os)->Preference->Editor->Live Templates-> Api|Api Tags`中查看详细模板内容，如json tag模板内容为 109 | ```go 110 | json:"$FIELD_NAME$" 111 | ``` 112 | ![context menu](./resource/json_tag.png) 113 | 114 | 115 | -------------------------------------------------------------------------------- /cn/join-us.md: -------------------------------------------------------------------------------- 1 | # 加入我们 2 | 3 | ## 概要 4 | go-zero 5 | 6 | [go-zero](https://github.com/tal-tech/go-zero) 是一个基于[MIT License](https://github.com/tal-tech/go-zero/blob/master/LICENSE) 的开源项目，大家在使用中发现bug，有新的特性等，均可以参与到go-zero的贡献中来，我们非常欢迎大家的积极参与，也会最快响应大家提出的各种问题，pr等。 7 | 8 | ## 贡献形式 9 | * [Pull Request](https://github.com/tal-tech/go-zero/pulls) 10 | * [Issue](https://github.com/tal-tech/go-zero/issues) 11 | 12 | ## 贡献须知 13 | go-zero 的Pull request中的代码需要满足一定规范 14 | * 命名规范，请阅读[命名规范](naming-spec.md) 15 | * 以英文注释为主 16 | * pr时备注好功能特性，描述需要清晰，简洁 17 | * 增加单元测试覆盖率达80%+ 18 | 19 | ## 贡献代码（pr） 20 | * 进入[go-zero](https://github.com/tal-tech/go-zero) 项目，fork一份[go-zero](https://github.com/tal-tech/go-zero) 项目到自己的github仓库中。 21 | * 回到自己的github主页，找到`xx/go-zero`项目，其中xx为你的用户名，如`anqiansong/go-zero` 22 | 23 | ![fork](./resource/fork.png) 24 | * 克隆代码到本地 25 | 26 | ![clone](./resource/clone.png) 27 | * 开发代码，push到自己的github仓库 28 | * 进入自己的github中go-zero项目，点击浮层上的的`【Pull requests】`进入Compare页面。 29 | 30 | ![pr](./resource/new_pr.png) 31 | 32 | * `base repository`选择`tal-tech/go-zero` `base:master`,`head repository`选择`xx/go-zero` `compare:$branch` ，`$branch`为你开发的分支，如图： 33 | 34 | ![pr](./resource/compare.png) 35 | 36 | * 点击`【Create pull request】`即可实现pr申请 37 | * 确认pr是否提交成功，进入[go-zero](https://github.com/tal-tech/go-zero) 的[Pull requests](https://github.com/tal-tech/go-zero/pulls) 查看，应该有自己提交的记录，名称为你的开发时的分支名称 38 | 39 | ![pr record](./resource/pr_record.png) 40 | 41 | ## Issue 42 | 在我们的社区中，有很多伙伴会积极的反馈一些go-zero使用过程中遇到的问题，由于社区人数较多，我们虽然会实时的关注社区动态，但大家问题反馈过来都是随机的，当我们团队还在解决某一个伙伴提出的问题时，另外的问题也反馈上来，可能会导致团队会很容易忽略掉，为了能够一一的解决大家的问题，我们强烈建议大家通过issue的方式来反馈问题，包括但不限于bug，期望的新功能特性等，我们在实现某一个新特性时也会在issue中体现，大家在这里也能够在这里获取到go-zero的最新动向，也欢迎大家来积极的参与讨论。 43 | 44 | ### 怎么提Issue 45 | * 点击[这里](https://github.com/tal-tech/go-zero/issues) 进入go-zero的Issue页面或者直接访问[https://github.com/tal-tech/go-zero/issues](https://github.com/tal-tech/go-zero/issues) 地址 46 | * 点击右上角的`【New issue】`新建issue 47 | * 填写issue标题和内容 48 | * 点击`【Submit new issue】`提交issue 49 | 50 | 51 | ## 参考文档 52 | 53 | * [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) -------------------------------------------------------------------------------- /cn/learning-resource.md: -------------------------------------------------------------------------------- 1 | # 学习资源 2 | 这里将不定期更新go-zero的最新学习资源通道，目前包含通道有： 3 | * [公众号](wechat.md) 4 | * [Go夜读](goreading.md) 5 | * [Go开源说](gotalk.md) -------------------------------------------------------------------------------- /cn/log-collection.md: -------------------------------------------------------------------------------- 1 | # 日志收集 2 | 为了保证业务稳定运行，预测服务不健康风险，日志的收集可以帮助我们很好的观察当前服务的健康状况， 3 | 在传统业务开发中，机器部署还不是很多时，我们一般都是直接登录服务器进行日志查看、调试，但随着业务的增大，服务的不断拆分， 4 | 服务的维护成本也会随之变得越来越复杂，在分布式系统中，服务器机子增多，服务分布在不同的服务器上，当遇到问题时， 5 | 我们不能使用传统做法，登录到服务器进行日志排查和调试，这个复杂度可想而知。 6 | ![log-flow](./resource/log-flow.png) 7 | 8 | > [!TIP] 9 | > 如果是一个简单的单体服务系统或者服务过于小不建议直接使用，否则会适得其反。 10 | 11 | ## 准备工作 12 | * kafka 13 | * elasticsearch 14 | * kibana 15 | * filebeat、Log-Pilot（k8s） 16 | * go-stash 17 | 18 | ## filebeat配置 19 | ```shell 20 | $ vim xx/filebeat.yaml 21 | ``` 22 | 23 | ```yaml 24 | filebeat.inputs: 25 | - type: log 26 | enabled: true 27 | # 开启json解析 28 | json.keys_under_root: true 29 | json.add_error_key: true 30 | # 日志文件路径 31 | paths: 32 | - /var/log/order/*.log 33 | 34 | setup.template.settings: 35 | index.number_of_shards: 1 36 | 37 | # 定义kafka topic field 38 | fields: 39 | log_topic: log-collection 40 | 41 | # 输出到kafka 42 | output.kafka: 43 | hosts: ["127.0.0.1:9092"] 44 | topic: '%{[fields.log_topic]}' 45 | partition.round_robin: 46 | reachable_only: false 47 | required_acks: 1 48 | keep_alive: 10s 49 | 50 | # ================================= Processors ================================= 51 | processors: 52 | - decode_json_fields: 53 | fields: ['@timestamp','level','content','trace','span','duration'] 54 | target: "" 55 | ``` 56 | 57 | > [!TIP] 58 | > xx为filebeat.yaml所在路径 59 | 60 | ## go-stash配置 61 | * 新建`config.yaml`文件 62 | * 添加配置内容 63 | 64 | ```shell 65 | $ vim config.yaml 66 | ``` 67 | 68 | ```yaml 69 | Clusters: 70 | - Input: 71 | Kafka: 72 | Name: go-stash 73 | Log: 74 | Mode: file 75 | Brokers: 76 | - "127.0.0.1:9092" 77 | Topics: 78 | - log-collection 79 | Group: stash 80 | Conns: 3 81 | Consumers: 10 82 | Processors: 60 83 | MinBytes: 1048576 84 | MaxBytes: 10485760 85 | Offset: first 86 | Filters: 87 | - Action: drop 88 | Conditions: 89 | - Key: status 90 | Value: "503" 91 | Type: contains 92 | - Key: type 93 | Value: "app" 94 | Type: match 95 | Op: and 96 | - Action: remove_field 97 | Fields: 98 | - source 99 | - _score 100 | - "@metadata" 101 | - agent 102 | - ecs 103 | - input 104 | - log 105 | - fields 106 | Output: 107 | ElasticSearch: 108 | Hosts: 109 | - "http://127.0.0.1:9200" 110 | Index: "go-stash-{{yyyy.MM.dd}}" 111 | MaxChunkBytes: 5242880 112 | GracePeriod: 10s 113 | Compress: false 114 | TimeZone: UTC 115 | ``` 116 | 117 | ## 启动服务(按顺序启动) 118 | * 启动kafka 119 | * 启动elasticsearch 120 | * 启动kibana 121 | * 启动go-stash 122 | * 启动filebeat 123 | * 启动order-api服务及其依赖服务（go-zero-demo工程中的order-api服务） 124 | 125 | ## 访问kibana 126 | 进入127.0.0.1:5601 127 | ![log](./resource/log.png) 128 | 129 | > [!TIP] 130 | > 这里仅演示收集服务中通过logx产生的日志，nginx中日志收集同理。 131 | 132 | 133 | # 参考文档 134 | * [kafka](http://kafka.apache.org/) 135 | * [elasticsearch](https://www.elastic.co/cn/elasticsearch/) 136 | * [kibana](https://www.elastic.co/cn/kibana) 137 | * [filebeat](https://www.elastic.co/cn/beats/filebeat) 138 | * [go-stash](https://github.com/tal-tech/go-stash) 139 | * [filebeat配置](https://www.elastic.co/guide/en/beats/filebeat/current/index.html) 140 | -------------------------------------------------------------------------------- /cn/middleware.md: -------------------------------------------------------------------------------- 1 | # 中间件使用 2 | 在上一节，我们演示了怎么使用jwt鉴权，相信你已经掌握了对jwt的基本使用，本节我们来看一下api服务中间件怎么使用。 3 | 4 | ## 中间件分类 5 | 在go-zero中，中间件可以分为路由中间件和全局中间件，路由中间件是指某一些特定路由需要实现中间件逻辑，其和jwt类似，没有放在`jwt:xxx`下的路由不会使用中间件功能， 6 | 而全局中间件的服务范围则是整个服务。 7 | 8 | ## 中间件使用 9 | 这里以`search`服务为例来演示中间件的使用 10 | 11 | ### 路由中间件 12 | * 重新编写`search.api`文件，添加`middleware`声明 13 | ```shell 14 | $ cd service/search/cmd/api 15 | $ vim search.api 16 | ``` 17 | ```text 18 | type SearchReq struct {} 19 | 20 | type SearchReply struct {} 21 | 22 | @server( 23 | jwt: Auth 24 | middleware: Example // 路由中间件声明 25 | ) 26 | service search-api { 27 | @handler search 28 | get /search/do (SearchReq) returns (SearchReply) 29 | } 30 | ``` 31 | * 重新生成api代码 32 | ```shell 33 | $ goctl api go -api search.api -dir . 34 | ``` 35 | ```text 36 | etc/search-api.yaml exists, ignored generation 37 | internal/config/config.go exists, ignored generation 38 | search.go exists, ignored generation 39 | internal/svc/servicecontext.go exists, ignored generation 40 | internal/handler/searchhandler.go exists, ignored generation 41 | internal/handler/pinghandler.go exists, ignored generation 42 | internal/logic/searchlogic.go exists, ignored generation 43 | internal/logic/pinglogic.go exists, ignored generation 44 | Done. 45 | ``` 46 | 生成完后会在`internal`目录下多一个`middleware`的目录，这里即中间件文件，后续中间件的实现逻辑也在这里编写。 47 | * 完善资源依赖`ServiceContext` 48 | ```shell 49 | $ vim service/search/cmd/api/internal/svc/servicecontext.go 50 | ``` 51 | ```go 52 | type ServiceContext struct { 53 | Config config.Config 54 | Example rest.Middleware 55 | } 56 | 57 | func NewServiceContext(c config.Config) *ServiceContext { 58 | return &ServiceContext{ 59 | Config: c, 60 | Example: middleware.NewExampleMiddleware().Handle, 61 | } 62 | } 63 | ``` 64 | * 编写中间件逻辑 65 | 这里仅添加一行日志，内容example middle，如果服务运行输出example middle则代表中间件使用起来了。 66 | 67 | ```shell 68 | $ vim service/search/cmd/api/internal/middleware/examplemiddleware.go 69 | ``` 70 | ```go 71 | package middleware 72 | 73 | import "net/http" 74 | 75 | type ExampleMiddleware struct { 76 | } 77 | 78 | func NewExampleMiddleware() *ExampleMiddleware { 79 | return &ExampleMiddleware{} 80 | } 81 | 82 | func (m *ExampleMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc { 83 | return func(w http.ResponseWriter, r *http.Request) { 84 | // TODO generate middleware implement function, delete after code implementation 85 | 86 | // Passthrough to next handler if need 87 | next(w, r) 88 | } 89 | } 90 | ``` 91 | * 启动服务验证 92 | ```text 93 | {"@timestamp":"2021-02-09T11:32:57.931+08","level":"info","content":"example middle"} 94 | ``` 95 | 96 | ### 全局中间件 97 | 通过rest.Server提供的Use方法即可 98 | ```go 99 | func main() { 100 | flag.Parse() 101 | 102 | var c config.Config 103 | conf.MustLoad(*configFile, &c) 104 | 105 | ctx := svc.NewServiceContext(c) 106 | server := rest.MustNewServer(c.RestConf) 107 | defer server.Stop() 108 | 109 | // 全局中间件 110 | server.Use(func(next http.HandlerFunc) http.HandlerFunc { 111 | return func(w http.ResponseWriter, r *http.Request) { 112 | logx.Info("global middleware") 113 | next(w, r) 114 | } 115 | }) 116 | handler.RegisterHandlers(server, ctx) 117 | 118 | fmt.Printf("Starting server at %s:%d...\n", c.Host, c.Port) 119 | server.Start() 120 | } 121 | ``` 122 | ```text 123 | {"@timestamp":"2021-02-09T11:50:15.388+08","level":"info","content":"global middleware"} 124 | ``` -------------------------------------------------------------------------------- /cn/model-gen.md: -------------------------------------------------------------------------------- 1 | # model生成 2 | 首先，下载好[演示工程](https://go-zero.dev/cn/resource/book.zip) 后，我们以user的model来进行代码生成演示。 3 | 4 | ## 前言 5 | model是服务访问持久化数据层的桥梁，业务的持久化数据常存在于mysql，mongo等数据库中，我们都知道，对于一个数据库的操作莫过于CURD， 6 | 而这些工作也会占用一部分时间来进行开发，我曾经在编写一个业务时写了40个model文件，根据不同业务需求的复杂性，平均每个model文件差不多需要 7 | 10分钟，对于40个文件来说，400分钟的工作时间，差不多一天的工作量，而goctl工具可以在10秒钟来完成这400分钟的工作。 8 | 9 | ## 准备工作 10 | 进入演示工程book，找到user/model下的user.sql文件，将其在你自己的数据库中执行建表。 11 | 12 | ## 代码生成(带缓存) 13 | ### 方式一(ddl) 14 | 进入`service/user/model`目录，执行命令 15 | ```shell 16 | $ cd service/user/model 17 | $ goctl model mysql ddl -src user.sql -dir . -c 18 | ``` 19 | ```text 20 | Done. 21 | ``` 22 | 23 | ### 方式二(datasource) 24 | ```shell 25 | $ goctl model mysql datasource -url="$datasource" -table="user" -c -dir . 26 | ``` 27 | ```text 28 | Done. 29 | ``` 30 | > [!TIP] 31 | > $datasource为数据库连接地址 32 | 33 | ### 方式三(intellij 插件) 34 | 在Goland中，右键`user.sql`，依次进入并点击`New`->`Go Zero`->`Model Code`即可生成，或者打开`user.sql`文件， 35 | 进入编辑区，使用快捷键`Command+N`（for mac OS）或者 `alt+insert`（for windows），选择`Mode Code`即可 36 | 37 | ![model生成](https://zeromicro.github.io/go-zero-pages/resource/intellij-model.png) 38 | 39 | > [!TIP] 40 | > intellij插件生成需要安装goctl插件，详情见[intellij插件](intellij.md) 41 | 42 | ## 验证生成的model文件 43 | 查看tree 44 | ```shell 45 | $ tree 46 | ``` 47 | ```text 48 | . 49 | ├── user.sql 50 | ├── usermodel.go 51 | └── vars.go 52 | ``` 53 | 54 | # 猜你想看 55 | [model命令及其原理](goctl-model.md) 56 | -------------------------------------------------------------------------------- /cn/monolithic-service.md: -------------------------------------------------------------------------------- 1 | # 单体服务 2 | 3 | ## 前言 4 | 由于go-zero集成了web/rpc于一体，社区有部分小伙伴会问我，go-zero的定位是否是一款微服务框架， 5 | 答案是否定的，go-zero虽然集众多功能于一身，但你可以将其中任何一个功能独立出来去单独使用，也可以开发单体服务， 6 | 不是说每个服务上来就一定要采用微服务的架构的设计，这点大家可以看看作者(kevin)的第四期[开源说](https://www.bilibili.com/video/BV1Jy4y127Xu) ，其中对此有详细的讲解。 7 | 8 | ## 创建greet服务 9 | ```shell 10 | $ cd ~/go-zero-demo 11 | $ goctl api new greet 12 | Done. 13 | ``` 14 | 15 | 查看一下`greet`服务的结构 16 | ```shell 17 | $ cd greet 18 | $ tree 19 | ``` 20 | ```text 21 | . 22 | ├── etc 23 | │   └── greet-api.yaml 24 | ├── greet.api 25 | ├── greet.go 26 | └── internal 27 | ├── config 28 | │   └── config.go 29 | ├── handler 30 | │   ├── greethandler.go 31 | │   └── routes.go 32 | ├── logic 33 | │   └── greetlogic.go 34 | ├── svc 35 | │   └── servicecontext.go 36 | └── types 37 | └── types.go 38 | ``` 39 | 由以上目录结构可以观察到，`greet`服务虽小，但"五脏俱全"。接下来我们就可以在`greetlogic.go`中编写业务代码了。 40 | 41 | ## 编写逻辑 42 | ```shell 43 | $ vim ~/go-zero-demo/greet/internal/logic/greetlogic.go 44 | ``` 45 | ```go 46 | func (l *GreetLogic) Greet(req types.Request) (*types.Response, error) { 47 | return &types.Response{ 48 | Message: "Hello go-zero", 49 | }, nil 50 | } 51 | ``` 52 | 53 | ## 启动并访问服务 54 | 55 | * 启动服务 56 | ```shell 57 | $ cd ~/go-zero-demo/greet 58 | $ go run greet.go -f etc/greet-api.yaml 59 | ``` 60 | ```text 61 | Starting server at 0.0.0.0:8888... 62 | ``` 63 | 64 | * 访问服务 65 | ```shell 66 | $ curl -i -X GET \ 67 | http://localhost:8888/from/you 68 | ``` 69 | 70 | ```text 71 | HTTP/1.1 200 OK 72 | Content-Type: application/json 73 | Date: Sun, 07 Feb 2021 04:31:25 GMT 74 | Content-Length: 27 75 | 76 | {"message":"Hello go-zero"} 77 | ``` 78 | 79 | # 源码 80 | [greet源码](https://github.com/zeromicro/go-zero-demo/tree/master/greet) 81 | 82 | # 猜你想看 83 | * [goctl使用说明](goctl.md) 84 | * [api目录结构介绍](api-dir.md) 85 | * [api语法](api-grammar.md) 86 | * [api配置文件介绍](api-config.md) 87 | * [api中间件使用](middleware.md) 88 | 89 | 90 | 91 | -------------------------------------------------------------------------------- /cn/naming-spec.md: -------------------------------------------------------------------------------- 1 | # 命名规范 2 | 在任何语言开发中，都有其语言领域的一些命名规范，好的命名可以： 3 | * 降低代码阅读成本 4 | * 降低维护难度 5 | * 降低代码复杂度 6 | 7 | ## 规范建议 8 | 在我们实际开发中，有很多开发人可能是由某一语言转到另外一个语言领域，在转到另外一门语言后， 9 | 我们都会保留着对旧语言的编程习惯，在这里，我建议的是，虽然不同语言之前的某些规范可能是相通的， 10 | 但是我们最好能够按照官方的一些demo来熟悉是渐渐适应当前语言的编程规范，而不是直接将原来语言的编程规范也随之迁移过来。 11 | 12 | ## 命名准则 13 | * 当变量名称在定义和最后一次使用之间的距离很短时，简短的名称看起来会更好。 14 | * 变量命名应尽量描述其内容，而不是类型 15 | * 常量命名应尽量描述其值，而不是如何使用这个值 16 | * 在遇到for，if等循环或分支时，推荐单个字母命名来标识参数和返回值 17 | * method、interface、type、package推荐使用单词命名 18 | * package名称也是命名的一部分，请尽量将其利用起来 19 | * 使用一致的命名风格 20 | 21 | ## 文件命名规范 22 | * 全部小写 23 | * 除unit test外避免下划线(_) 24 | * 文件名称不宜过长 25 | 26 | ## 变量命名规范参考 27 | * 首字母小写 28 | * 驼峰命名 29 | * 见名知义，避免拼音替代英文 30 | * 不建议包含下划线(_) 31 | * 不建议包含数字 32 | 33 | **适用范围** 34 | * 局部变量 35 | * 函数出参、入参 36 | 37 | ## 函数、常量命名规范 38 | * 驼峰式命名 39 | * 可exported的必须首字母大写 40 | * 不可exported的必须首字母小写 41 | * 避免全部大写与下划线(_)组合 42 | 43 | 44 | > [!TIP] 45 | > 如果是go-zero代码贡献，则必须严格遵循此命名规范 46 | 47 | 48 | # 参考文档 49 | * [Practical Go: Real world advice for writing maintainable Go programs](https://dave.cheney.net/practical-go/presentations/gophercon-singapore-2019.html#_simplicity) 50 | -------------------------------------------------------------------------------- /cn/plugin-center.md: -------------------------------------------------------------------------------- 1 | # 插件中心 2 | goctl api提供了对plugin命令来支持对api进行功能扩展，当goctl api中的功能不满足你的使用， 3 | 或者需要对goctl api进行功能自定义的扩展，那么插件功能将非常适合开发人员进行自给自足，详情见 4 | [goctl plugin](goctl-plugin.md) 5 | 6 | ## 插件资源 7 | * [goctl-go-compact](https://github.com/zeromicro/goctl-go-compact) 8 | goctl默认的一个路由一个文件合并成一个文件 9 | * [goctl-swagger](https://github.com/zeromicro/goctl-swagger) 10 | 通过api文件生成swagger文档 11 | * [goctl-php](https://github.com/zeromicro/goctl-php) 12 | goctl-php是一款基于goctl的插件，用于生成 php 调用端（服务端） http server请求代码 13 | 14 | # 猜你想看 15 | * [goctl插件](goctl-plugin.md) 16 | * [api语法介绍](api-grammar.md) -------------------------------------------------------------------------------- /cn/practise.md: -------------------------------------------------------------------------------- 1 | # 开发实践 2 | * [go-zero缓存设计之持久层缓存](redis-cache.md) 3 | * [go-zero缓存设计之业务层缓存](buiness-cache.md) 4 | * [go-zero分布式定时任务](go-queue.md) 5 | * [我是如何用go-zero 实现一个中台系统](datacenter.md) 6 | * [流数据处理利器](stream.md) 7 | * [10月3日线上交流问题汇总](online-exchange.md) -------------------------------------------------------------------------------- /cn/prepare-other.md: -------------------------------------------------------------------------------- 1 | # 其他 2 | 在之前我们已经对Go环境、Go Module配置、Goctl、protoc&protoc-gen-go安装准备就绪，这些是开发人员在开发阶段必须要准备的环境，而接下来的环境你可以选择性的安装， 3 | 因为这些环境一般存在于服务器（安装工作运维会替你完成），但是为了后续**演示**流程能够完整走下去，我建议大家在本地也安装一下，因为我们的演示环境大部分会以本地为主。 4 | 以下仅给出了需要的准备工作，不以文档篇幅作详细介绍了。 5 | 6 | ## 其他环境 7 | * [etcd](https://etcd.io/docs/current/rfc/v3api/) 8 | * [redis](https://redis.io/) 9 | * [mysql](https://www.mysql.com/) -------------------------------------------------------------------------------- /cn/prepare.md: -------------------------------------------------------------------------------- 1 | # 准备工作 2 | 在正式进入实际开发之前，我们需要做一些准备工作，比如：Go环境的安装，grpc代码生成使用的工具安装， 3 | 必备工具Goctl的安装，Golang环境配置等，本节将包含以下小节： 4 | * [golang安装](golang-install.md) 5 | * [go modudle配置](gomod-config.md) 6 | * [goctl安装](goctl-install.md) 7 | * [protoc&protoc-gen-go安装](protoc-install.md) 8 | * [其他](prepare-other.md) -------------------------------------------------------------------------------- /cn/project-dev.md: -------------------------------------------------------------------------------- 1 | # 项目开发 2 | 在前面的章节我们已经从一些概念、背景、快速入门等维度介绍了一下go-zero，看到这里，相信你对go-zero已经有了一些了解， 3 | 从这里开始，我们将会从环境准备到服务部署整个流程开始进行讲解，为了保证大家能够彻底弄懂go-zero的开发流程，那就准备你的耐心来接着往下走吧。 4 | 在章节中，将包含以下小节： 5 | * [准备工作](prepare.md) 6 | * [golang安装](golang-install.md) 7 | * [go modudle配置](gomod-config.md) 8 | * [goctl安装](goctl-install.md) 9 | * [protoc&protoc-gen-go安装](protoc-install.md) 10 | * [其他](prepare-other.md) 11 | * [开发规范](dev-specification.md) 12 | * [命名规范](naming-spec.md) 13 | * [路由规范](route-naming-spec.md) 14 | * [编码规范](coding-spec.md) 15 | * [开发流程](dev-flow.md) 16 | * [配置介绍](config-introduction.md) 17 | * [api配置](api-config.md) 18 | * [rpc配置](rpc-config.md) 19 | * [业务开发](business-dev.md) 20 | * [目录拆分](service-design.md) 21 | * [model生成](model-gen.md) 22 | * [api文件编写](api-coding.md) 23 | * [业务编码](business-coding.md) 24 | * [jwt鉴权](jwt.md) 25 | * [中间件使用](middleware.md) 26 | * [rpc服务编写与调用](rpc-call.md) 27 | * [错误处理](error-handle.md) 28 | * [CI/CD](ci-cd.md) 29 | * [服务部署](service-deployment.md) 30 | * [日志收集](log-collection.md) 31 | * [链路追踪](trace.md) 32 | * [服务监控](service-monitor.md) -------------------------------------------------------------------------------- /cn/protoc-install.md: -------------------------------------------------------------------------------- 1 | # protoc & protoc-gen-go安装 2 | 3 | ## 前言 4 | protoc是一款用C++编写的工具，其可以将proto文件翻译为指定语言的代码。在go-zero的微服务中，我们采用grpc进行服务间的通信，而grpc的编写就需要用到protoc和翻译成go语言rpc stub代码的插件protoc-gen-go。 5 | 6 | 本文演示环境 7 | * mac OS 8 | * protoc 3.14.0 9 | 10 | ## protoc安装 11 | 12 | * 进入[protobuf release](https://github.com/protocolbuffers/protobuf/releases) 页面，选择适合自己操作系统的压缩包文件 13 | * 解压`protoc-3.14.0-osx-x86_64.zip`并进入`protoc-3.14.0-osx-x86_64` 14 | ```shell 15 | $ cd protoc-3.14.0-osx-x86_64/bin 16 | ``` 17 | * 将启动的`protoc`二进制文件移动到被添加到环境变量的任意path下，如`$GOPATH/bin`，这里不建议直接将其和系统的以下path放在一起。 18 | ```shell 19 | $ mv protoc $GOPATH/bin 20 | ``` 21 | > [!TIP] 22 | > $GOPATH为你本机的实际文件夹地址 23 | * 验证安装结果 24 | ```shell 25 | $ protoc --version 26 | ``` 27 | ```shell 28 | libprotoc 3.14.0 29 | ``` 30 | 31 | ## protoc-gen-*安装 32 | 在goctl版本大于1.2.1时，则不需要安装 `protoc-gen-go` 插件了，因为在该版本以后，goctl已经实现了作为 `protoc` 的插件了，goctl在指定 `goctl xxx` 命令时会自动 33 | 将 `goctl` 创建一个符号链接 `protoc-gen-goctl` ，在生成pb.go时会按照如下逻辑生成： 34 | 1. 检测环境变量中是否存在 `protoc-gen-goctl` 插件，如果是，则跳转到第3步 35 | 2. 检测环境变量中是否存在 `protoc-gen-go` 插件，如果不存在，则生成流程结束 36 | 3. 根据检测到的插件生成pb.go 37 | 38 | > [!TIPS] 39 | > 40 | > Windows 在创建符号链接可能会报错， `A required privilege is not held by the client.`, 原因是在Windows下执行goctl需要"以管理员身份"运行。 41 | > 42 | 43 | * 下载安装`protoc-gen-go` 44 | 45 | 如果goctl 版本已经是1.2.1以后了，可以忽略此步骤。 46 | ```shell 47 | $ go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2 48 | ``` 49 | ```text 50 | go: found github.com/golang/protobuf/protoc-gen-go in github.com/golang/protobuf v1.4.3 51 | go: google.golang.org/protobuf upgrade => v1.25.0 52 | ``` 53 | * 将protoc-gen-go移动到被添加环境变量的任意path下，如`$GOPATH/bin`，由于`go get`后的二进制本身就在`$GOPATH/bin`目录中，因此只要确保你的`$GOPATH/bin`在环境变量即可。 54 | 55 | > **[!WARNING] 56 | > protoc-gen-go安装失败请阅读[常见错误处理](error.md) 57 | -------------------------------------------------------------------------------- /cn/quick-start.md: -------------------------------------------------------------------------------- 1 | # 快速开发 2 | 3 | 本节主要通过对 api/rpc 等服务快速开始来让大家对使用 go-zero 开发的工程有一个宏观概念，更加详细的介绍我们将在后续一一展开。如果您已经参考 [准备工作](prepare.md) 做好环境及工具的准备，请跟随以下小节开始体验： 4 | 5 | * [单体服务](monolithic-service.md) 6 | * [微服务](micro-service.md) 7 | -------------------------------------------------------------------------------- /cn/redis-lock.md: -------------------------------------------------------------------------------- 1 | # redis-lock 2 | 3 | # redis lock 4 | 5 | 既然是锁，首先想到的一个作用就是：**防重复点击，在一个时间点只有一个请求产生效果**。 6 | 7 | 8 | 而既然是 `redis`，就得具有排他性，同时也具有锁的一些共性： 9 | 10 | 11 | - 高性能 12 | - 不能出现死锁 13 | - 不能出现节点down掉后加锁失败 14 | 15 | 16 | 17 | `go-zero` 中利用 redis `set key nx` 可以保证key不存在时写入成功，`px` 可以让key超时后自动删除「最坏情况也就是超时自动删除key，从而也不会出现死锁」 18 | 19 | 20 | ## example 21 | 22 | 23 | ```go 24 | redisLockKey := fmt.Sprintf("%v%v", redisTpl, headId) 25 | // 1. New redislock 26 | redisLock := redis.NewRedisLock(redisConn, redisLockKey) 27 | // 2. 可选操作，设置 redislock 过期时间 28 | redisLock.SetExpire(redisLockExpireSeconds) 29 | if ok, err := redisLock.Acquire(); !ok || err != nil { 30 | return nil, errors.New("当前有其他用户正在进行操作，请稍后重试") 31 | } 32 | defer func() { 33 | recover() 34 | // 3. 释放锁 35 | redisLock.Release() 36 | }() 37 | ``` 38 | 39 | 40 | 和你在使用 `sync.Mutex` 的方式时一致的。加锁解锁，执行你的业务操作。 41 | 42 | 43 | ## 获取锁 44 | 45 | 46 | ```go 47 | lockCommand = `if redis.call("GET", KEYS[1]) == ARGV[1] then 48 | redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[2]) 49 | return "OK" 50 | else 51 | return redis.call("SET", KEYS[1], ARGV[1], "NX", "PX", ARGV[2]) 52 | end` 53 | 54 | func (rl *RedisLock) Acquire() (bool, error) { 55 | seconds := atomic.LoadUint32(&rl.seconds) 56 | // execute luascript 57 | resp, err := rl.store.Eval(lockCommand, []string{rl.key}, []string{ 58 | rl.id, strconv.Itoa(int(seconds)*millisPerSecond + tolerance)}) 59 | if err == red.Nil { 60 | return false, nil 61 | } else if err != nil { 62 | logx.Errorf("Error on acquiring lock for %s, %s", rl.key, err.Error()) 63 | return false, err 64 | } else if resp == nil { 65 | return false, nil 66 | } 67 | 68 | reply, ok := resp.(string) 69 | if ok && reply == "OK" { 70 | return true, nil 71 | } else { 72 | logx.Errorf("Unknown reply when acquiring lock for %s: %v", rl.key, resp) 73 | return false, nil 74 | } 75 | } 76 | ``` 77 | 78 | 79 | 先介绍几个 `redis` 的命令选项，以下是为 `set` 命令增加的选项： 80 | 81 | 82 | - `ex seconds` ：设置key过期时间，单位s 83 | - `px milliseconds` ：设置key过期时间，单位毫秒 84 | - `nx`：key不存在时，设置key的值 85 | - `xx`：key存在时，才会去设置key的值 86 | 87 | 88 | 89 | 其中 `lua script` 涉及的入参： 90 | 91 | 92 | 93 | | args | 示例 | 含义 | 94 | | --- | --- | --- | 95 | | KEYS[1] | key$20201026 | redis key | 96 | | ARGV[1] | lmnopqrstuvwxyzABCD | 唯一标识：随机字符串 | 97 | | ARGV[2] | 30000 | 设置锁的过期时间 | 98 | 99 | 100 | 101 | 然后来说说代码特性： 102 | 103 | 104 | 1. `Lua` 脚本保证原子性「当然，把多个操作在 Redis 中实现成一个操作，也就是单命令操作」 105 | 1. 使用了 `set key value px milliseconds nx` 106 | 1. `value` 具有唯一性 107 | 1. 加锁时首先判断 `key` 的 `value` 是否和之前设置的一致，一致则修改过期时间 108 | 109 | 110 | 111 | ## 释放锁 112 | 113 | 114 | ```go 115 | delCommand = `if redis.call("GET", KEYS[1]) == ARGV[1] then 116 | return redis.call("DEL", KEYS[1]) 117 | else 118 | return 0 119 | end` 120 | 121 | func (rl *RedisLock) Release() (bool, error) { 122 | resp, err := rl.store.Eval(delCommand, []string{rl.key}, []string{rl.id}) 123 | if err != nil { 124 | return false, err 125 | } 126 | 127 | if reply, ok := resp.(int64); !ok { 128 | return false, nil 129 | } else { 130 | return reply == 1, nil 131 | } 132 | } 133 | ``` 134 | 135 | 136 | 释放锁的时候只需要关注一点： 137 | 138 | 139 | **不能释放别人的锁，不能释放别人的锁，不能释放别人的锁** 140 | 141 | 142 | 所以需要先 `get(key) == value「key」`，为 true 才会去 `delete` 143 | -------------------------------------------------------------------------------- /cn/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png -------------------------------------------------------------------------------- /cn/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png -------------------------------------------------------------------------------- /cn/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png -------------------------------------------------------------------------------- /cn/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png -------------------------------------------------------------------------------- /cn/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png -------------------------------------------------------------------------------- /cn/resource/alert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/alert.png -------------------------------------------------------------------------------- /cn/resource/api-compare.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/api-compare.png -------------------------------------------------------------------------------- /cn/resource/api-new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/api-new.png -------------------------------------------------------------------------------- /cn/resource/author.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/author.jpeg -------------------------------------------------------------------------------- /cn/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png -------------------------------------------------------------------------------- /cn/resource/book.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/book.zip -------------------------------------------------------------------------------- /cn/resource/c42c34e8d33d48ec8a63e56feeae882a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/c42c34e8d33d48ec8a63e56feeae882a.png -------------------------------------------------------------------------------- /cn/resource/ci-cd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/ci-cd.png -------------------------------------------------------------------------------- /cn/resource/clone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/clone.png -------------------------------------------------------------------------------- /cn/resource/compare.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/compare.png -------------------------------------------------------------------------------- /cn/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png -------------------------------------------------------------------------------- /cn/resource/doc-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/doc-edit.png -------------------------------------------------------------------------------- /cn/resource/docker_env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/docker_env.png -------------------------------------------------------------------------------- /cn/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png -------------------------------------------------------------------------------- /cn/resource/fork.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/fork.png -------------------------------------------------------------------------------- /cn/resource/fx_log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/fx_log.png -------------------------------------------------------------------------------- /cn/resource/gitlab-git-url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/gitlab-git-url.png -------------------------------------------------------------------------------- /cn/resource/go-zero-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/go-zero-logo.png -------------------------------------------------------------------------------- /cn/resource/go-zero-practise.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/go-zero-practise.png -------------------------------------------------------------------------------- /cn/resource/go_live_template.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/go_live_template.png -------------------------------------------------------------------------------- /cn/resource/goctl-api-select.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/goctl-api-select.png -------------------------------------------------------------------------------- /cn/resource/goctl-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/goctl-api.png -------------------------------------------------------------------------------- /cn/resource/goctl-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/goctl-command.png -------------------------------------------------------------------------------- /cn/resource/grafana-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/grafana-app.png -------------------------------------------------------------------------------- /cn/resource/grafana-panel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/grafana-panel.png -------------------------------------------------------------------------------- /cn/resource/grafana-qps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/grafana-qps.png -------------------------------------------------------------------------------- /cn/resource/grafana.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/grafana.png -------------------------------------------------------------------------------- /cn/resource/handler.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/handler.gif -------------------------------------------------------------------------------- /cn/resource/info.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/info.gif -------------------------------------------------------------------------------- /cn/resource/intellij-model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/intellij-model.png -------------------------------------------------------------------------------- /cn/resource/jenkins-add-credentials.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-add-credentials.png -------------------------------------------------------------------------------- /cn/resource/jenkins-build-with-parameters.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-build-with-parameters.png -------------------------------------------------------------------------------- /cn/resource/jenkins-choice.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-choice.png -------------------------------------------------------------------------------- /cn/resource/jenkins-configure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-configure.png -------------------------------------------------------------------------------- /cn/resource/jenkins-credentials-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-credentials-id.png -------------------------------------------------------------------------------- /cn/resource/jenkins-credentials.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-credentials.png -------------------------------------------------------------------------------- /cn/resource/jenkins-git.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-git.png -------------------------------------------------------------------------------- /cn/resource/jenkins-new-item.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jenkins-new-item.png -------------------------------------------------------------------------------- /cn/resource/json_tag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/json_tag.png -------------------------------------------------------------------------------- /cn/resource/jump.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/jump.gif -------------------------------------------------------------------------------- /cn/resource/k8s-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/k8s-01.png -------------------------------------------------------------------------------- /cn/resource/k8s-02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/k8s-02.png -------------------------------------------------------------------------------- /cn/resource/k8s-03.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/k8s-03.png -------------------------------------------------------------------------------- /cn/resource/live_template.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/live_template.gif -------------------------------------------------------------------------------- /cn/resource/log-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/log-flow.png -------------------------------------------------------------------------------- /cn/resource/log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/log.png -------------------------------------------------------------------------------- /cn/resource/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/logo.png -------------------------------------------------------------------------------- /cn/resource/new_pr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/new_pr.png -------------------------------------------------------------------------------- /cn/resource/pipeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/pipeline.png -------------------------------------------------------------------------------- /cn/resource/pr_record.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/pr_record.png -------------------------------------------------------------------------------- /cn/resource/project_generate_code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/project_generate_code.png -------------------------------------------------------------------------------- /cn/resource/prometheus-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/prometheus-flow.png -------------------------------------------------------------------------------- /cn/resource/prometheus-graph.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/prometheus-graph.webp -------------------------------------------------------------------------------- /cn/resource/prometheus-start.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/prometheus-start.png -------------------------------------------------------------------------------- /cn/resource/psiTree.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/psiTree.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-01.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-02.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-03.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-03.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-04.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-04.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-05.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-05.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-06.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-06.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-07.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-07.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-08.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-08.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-09.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-09.webp -------------------------------------------------------------------------------- /cn/resource/redis-cache-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-10.png -------------------------------------------------------------------------------- /cn/resource/redis-cache-11.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/redis-cache-11.webp -------------------------------------------------------------------------------- /cn/resource/service.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/service.gif -------------------------------------------------------------------------------- /cn/resource/service.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/service.png -------------------------------------------------------------------------------- /cn/resource/ssh-add-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/ssh-add-key.png -------------------------------------------------------------------------------- /cn/resource/type.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/type.gif -------------------------------------------------------------------------------- /cn/resource/user-pipeline-script.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/cn/resource/user-pipeline-script.png -------------------------------------------------------------------------------- /cn/route-naming-spec.md: -------------------------------------------------------------------------------- 1 | # 路由规范 2 | * 推荐脊柱式命名 3 | * 小写单词、横杠(-)组合 4 | * 见名知义 5 | 6 | ```go 7 | /user/get-info 8 | /user/get/info 9 | /user/password/change/:id 10 | ``` -------------------------------------------------------------------------------- /cn/rpc-config.md: -------------------------------------------------------------------------------- 1 | # rpc配置 2 | 3 | rpc配置控制着一个rpc服务的各种功能，包含但不限于监听地址，etcd配置，超时，熔断配置等，下面我们以一个常见的rpc服务配置来进行说明。 4 | 5 | ## 配置说明 6 | ```go 7 | Config struct { 8 | zrpc.RpcServerConf 9 | CacheRedis cache.CacheConf // redis缓存配置，详情见api配置说明，这里不赘述 10 | Mysql struct { // mysql数据库访问配置，详情见api配置说明，这里不赘述 11 | DataSource string 12 | } 13 | } 14 | ``` 15 | 16 | ### zrpc.RpcServerConf 17 | ```go 18 | RpcServerConf struct { 19 | service.ServiceConf // 服务配置，详情见api配置说明，这里不赘述 20 | ListenOn string // rpc监听地址和端口，如：127.0.0.1:8888 21 | Etcd discov.EtcdConf `json:",optional"` // etcd相关配置 22 | Auth bool `json:",optional"` // 是否开启Auth，如果是则Redis为必填 23 | Redis redis.RedisKeyConf `json:",optional"` // Auth验证 24 | StrictControl bool `json:",optional"` // 是否Strict模式，如果是则遇到错误是Auth失败，否则可以认为成功 25 | // pending forever is not allowed 26 | // never set it to 0, if zero, the underlying will set to 2s automatically 27 | Timeout int64 `json:",default=2000"` // 超时控制，单位：毫秒 28 | CpuThreshold int64 `json:",default=900,range=[0:1000]"` cpu降载阈值，默认900，可允许设置范围0到1000 29 | } 30 | ``` 31 | 32 | ### discov.EtcdConf 33 | ```go 34 | type EtcdConf struct { 35 | Hosts []string // etcd host数组 36 | Key string // rpc注册key 37 | } 38 | ``` 39 | 40 | ### redis.RedisKeyConf 41 | ```go 42 | RedisConf struct { 43 | Host string // redis 主机 44 | Type string `json:",default=node,options=node|cluster"` // redis类型 45 | Pass string `json:",optional"` // redis密码 46 | } 47 | 48 | RedisKeyConf struct { 49 | RedisConf 50 | Key string `json:",optional"` // 验证key 51 | } 52 | ``` 53 | -------------------------------------------------------------------------------- /cn/rpc-dir.md: -------------------------------------------------------------------------------- 1 | # rpc服务目录 2 | 3 | ```text 4 | . 5 | ├── etc // yaml配置文件 6 | │ └── greet.yaml 7 | ├── go.mod 8 | ├── greet // pb.go文件夹① 9 | │ └── greet.pb.go 10 | ├── greet.go // main函数 11 | ├── greet.proto // proto 文件 12 | ├── greetclient // call logic ② 13 | │ └── greet.go 14 | └── internal 15 | ├── config // yaml配置对应的实体 16 | │ └── config.go 17 | ├── logic // 业务代码 18 | │ └── pinglogic.go 19 | ├── server // rpc server 20 | │ └── greetserver.go 21 | └── svc // 依赖资源 22 | └── servicecontext.go 23 | ``` 24 | 25 | > [!TIP] 26 | > ① pb文件夹名（老版本文件夹固定为pb）称取自于proto文件中option go_package的值最后一层级按照一定格式进行转换，若无此声明，则取自于package的值，大致代码如下： 27 | 28 | ```go 29 | if option.Name == "go_package" { 30 | ret.GoPackage = option.Constant.Source 31 | } 32 | ... 33 | if len(ret.GoPackage) == 0 { 34 | ret.GoPackage = ret.Package.Name 35 | } 36 | ret.PbPackage = GoSanitized(filepath.Base(ret.GoPackage)) 37 | ... 38 | ``` 39 | > [!TIP] 40 | > GoSanitized方法请参考google.golang.org/protobuf@v1.25.0/internal/strs/strings.go:71 41 | 42 | > [!TIP] 43 | > ② call 层文件夹名称取自于proto中service的名称，如该sercice的名称和pb文件夹名称相等，则会在srervice后面补充client进行区分，使pb和call分隔。 44 | 45 | ```go 46 | if strings.ToLower(proto.Service.Name) == strings.ToLower(proto.GoPackage) { 47 | callDir = filepath.Join(ctx.WorkDir, strings.ToLower(stringx.From(proto.Service.Name+"_client").ToCamel())) 48 | } 49 | ``` -------------------------------------------------------------------------------- /cn/service-design.md: -------------------------------------------------------------------------------- 1 | # 目录拆分 2 | 目录拆分是指配合go-zero的最佳实践的目录拆分，这和微服务拆分有着关联，在团队内部最佳实践中， 3 | 我们按照业务横向拆分，将一个系统拆分成多个子系统，每个子系统应拥有独立的持久化存储，缓存系统。 4 | 如一个商城系统需要有用户系统(user)，商品管理系统(product)，订单系统(order)，购物车系统(cart)，结算中心系统(pay)，售后系统(afterSale)等组成。 5 | 6 | ## 系统结构分析 7 | 在上文提到的商城系统中，每个系统在对外（http）提供服务的同时，也会提供数据给其他子系统进行数据访问的接口（rpc），因此每个子系统可以拆分成一个服务，而且对外提供了两种访问该系统的方式api和rpc，因此， 8 | 以上系统按照目录结构来拆分有如下结构: 9 | 10 | ```text 11 | . 12 | ├── afterSale 13 | │   ├── api 14 | │   └── rpc 15 | ├── cart 16 | │   ├── api 17 | │   └── rpc 18 | ├── order 19 | │   ├── api 20 | │   └── rpc 21 | ├── pay 22 | │   ├── api 23 | │   └── rpc 24 | ├── product 25 | │   ├── api 26 | │   └── rpc 27 | └── user 28 | ├── api 29 | └── rpc 30 | ``` 31 | 32 | ## rpc调用链建议 33 | 在设计系统时，尽量做到服务之间调用链是单向的，而非循环调用，例如：order服务调用了user服务，而user服务反过来也会调用order的服务， 34 | 当其中一个服务启动故障，就会相互影响，进入死循环，你order认为是user服务故障导致的，而user认为是order服务导致的，如果有大量服务存在相互调用链， 35 | 则需要考虑服务拆分是否合理。 36 | 37 | ## 常见服务类型的目录结构 38 | 在上述服务中，仅列举了api/rpc服务，除此之外，一个服务下还可能有其他更多服务类型，如rmq（消息处理系统），cron（定时任务系统），script（脚本）等， 39 | 因此一个服务下可能包含以下目录结构： 40 | ```text 41 | user 42 | ├── api // http访问服务，业务需求实现 43 | ├── cronjob // 定时任务，定时数据更新业务 44 | ├── rmq // 消息处理系统：mq和dq，处理一些高并发和延时消息业务 45 | ├── rpc // rpc服务，给其他子系统提供基础数据访问 46 | └── script // 脚本，处理一些临时运营需求，临时数据修复 47 | ``` 48 | 49 | ## 完整工程目录结构示例 50 | ```text 51 | mall // 工程名称 52 | ├── common // 通用库 53 | │   ├── randx 54 | │   └── stringx 55 | ├── go.mod 56 | ├── go.sum 57 | └── service // 服务存放目录 58 | ├── afterSale 59 | │   ├── api 60 | │   └── model 61 | │   └── rpc 62 | ├── cart 63 | │   ├── api 64 | │   └── model 65 | │   └── rpc 66 | ├── order 67 | │   ├── api 68 | │   └── model 69 | │   └── rpc 70 | ├── pay 71 | │   ├── api 72 | │   └── model 73 | │   └── rpc 74 | ├── product 75 | │   ├── api 76 | │   └── model 77 | │   └── rpc 78 | └── user 79 | ├── api 80 | ├── cronjob 81 | ├── model 82 | ├── rmq 83 | ├── rpc 84 | └── script 85 | ``` 86 | 87 | # 猜你想看 88 | * [api目录结构介绍](api-dir.md) 89 | -------------------------------------------------------------------------------- /cn/service-monitor.md: -------------------------------------------------------------------------------- 1 | # 服务监控 2 | 在微服务治理中，服务监控也是非常重要的一个环节，监控一个服务是否正常工作，需要从多维度进行，如： 3 | * mysql指标 4 | * mongo指标 5 | * redis指标 6 | * 请求日志 7 | * 服务指标统计 8 | * 服务健康检测 9 | ... 10 | 11 | 监控的工作非常大，本节仅以其中的`服务指标监控`作为例子进行说明。 12 | 13 | ## 基于prometheus的微服务指标监控 14 | 15 | 服务上线后我们往往需要对服务进行监控，以便能及早发现问题并做针对性的优化，监控又可分为多种形式，比如日志监控，调用链监控，指标监控等等。而通过指标监控能清晰的观察出服务指标的变化趋势，了解服务的运行状态，对于保证服务稳定起着非常重要的作用 16 | prometheus是一个开源的系统监控和告警工具，支持强大的查询语言PromQL允许用户实时选择和汇聚时间序列数据，时间序列数据是服务端通过HTTP协议主动拉取获得，也可以通过中间网关来推送时间序列数据，可以通过静态配置文件或服务发现来获取监控目标 17 | 18 | ##Prometheus 的架构 19 | 20 | Prometheus 的整体架构以及生态系统组件如下图所示： 21 | ![prometheus-flow](./resource/prometheus-flow.png) 22 | 23 | Prometheus Server直接从监控目标中或者间接通过推送网关来拉取监控指标，它在本地存储所有抓取到样本数据，并对此数据执行一系列规则，以汇总和记录现有数据的新时间序列或生成告警。可以通过 Grafana 或者其他工具来实现监控数据的可视化 24 | 25 | ## go-zero基于prometheus的服务指标监控 26 | 27 | go-zero 框架中集成了基于prometheus的服务指标监控，下面我们通过go-zero官方的示例shorturl来演示是如何对服务指标进行收集监控的： 28 | * 第一步需要先安装Prometheus，安装步骤请参考官方文档 29 | * go-zero默认不开启prometheus监控，开启方式很简单，只需要在shorturl-api.yaml文件中增加配置如下，其中Host为Prometheus Server地址为必填配置，Port端口不填默认9091，Path为用来拉取指标的路径默认为/metrics 30 | ```yaml 31 | Prometheus: 32 | Host: 127.0.0.1 33 | Port: 9091 34 | Path: /metrics 35 | ``` 36 | 37 | * 编辑prometheus的配置文件prometheus.yml，添加如下配置，并创建targets.json 38 | ```yaml 39 | - job_name: 'file_ds' 40 | file_sd_configs: 41 | - files: 42 | - targets.json 43 | ``` 44 | * 编辑targets.json文件，其中targets为shorturl配置的目标地址，并添加了几个默认的标签 45 | ```yaml 46 | [ 47 | { 48 | "targets": ["127.0.0.1:9091"], 49 | "labels": { 50 | "job": "shorturl-api", 51 | "app": "shorturl-api", 52 | "env": "test", 53 | "instance": "127.0.0.1:8888" 54 | } 55 | } 56 | ] 57 | ``` 58 | * 启动prometheus服务，默认侦听在9090端口 59 | ```shell 60 | $ prometheus --config.file=prometheus.yml 61 | ``` 62 | * 在浏览器输入`http://127.0.0.1:9090/`，然后点击`Status` -> `Targets`即可看到状态为Up的Job，并且Lables栏可以看到我们配置的默认的标签 63 | ![prometheus-start](./resource/prometheus-start.png) 64 | 通过以上几个步骤我们完成了prometheus对shorturl服务的指标监控收集的配置工作，为了演示简单我们进行了手动的配置，在实际的生产环境中一般采用定时更新配置文件或者服务发现的方式来配置监控目标，篇幅有限这里不展开讲解，感兴趣的同学请自行查看相关文档 65 | 66 | ## go-zero监控的指标类型 67 | 68 | go-zero目前在http的中间件和rpc的拦截器中添加了对请求指标的监控。 69 | 70 | 主要从请求耗时和请求错误两个维度，请求耗时采用了Histogram指标类型定义了多个Buckets方便进行分位统计，请求错误采用了Counter类型，并在http metric中添加了path标签rpc metric中添加了method标签以便进行细分监控。 71 | 接下来演示如何查看监控指标： 72 | 首先在命令行多次执行如下命令 73 | ```shell 74 | $ curl -i "http://localhost:8888/shorten?url=http://www.xiaoheiban.cn" 75 | ``` 76 | 打开Prometheus切换到Graph界面，在输入框中输入{path="/shorten"}指令，即可查看监控指标，如下图 77 | ![prometheus-graph](./resource/prometheus-graph.webp) 78 | 79 | 我们通过PromQL语法查询过滤path为/shorten的指标，结果中显示了指标名以及指标数值，其中http_server_requests_code_total指标中code值为http的状态码，200表明请求成功，http_server_requests_duration_ms_bucket中对不同bucket结果分别进行了统计，还可以看到所有的指标中都添加了我们配置的默认指标 80 | Console界面主要展示了查询的指标结果，Graph界面为我们提供了简单的图形化的展示界面，在实际的生产环境中我们一般使用Grafana做图形化的展示 81 | 82 | ## grafana可视化界面 83 | 84 | grafana是一款可视化工具，功能强大，支持多种数据来源Prometheus、Elasticsearch、Graphite等，安装比较简单请参考官方文档，grafana默认端口3000，安装好后再浏览器输入http://localhost:3000/，默认账号和密码都为admin 85 | 下面演示如何基于以上指标进行可视化界面的绘制： 86 | 点击左侧边栏`Configuration`->`Data Source`->`Add data source`进行数据源添加，其中HTTP的URL为数据源的地址 87 | ![grafana](./resource/grafana.png) 88 | 89 | 点击左侧边栏添加dashboard，然后添加Variables方便针对不同的标签进行过滤筛选比如添加app变量用来过滤不同的服务 90 | ![grafana-app](./resource/grafana-app.png) 91 | 92 | 进入dashboard点击右上角Add panel添加面板，以path维度统计接口的qps 93 | ![grafana-app](./resource/grafana-qps.png) 94 | 95 | 最终的效果如下所示，可以通过服务名称过滤不同的服务，面板展示了path为/shorten的qps变化趋势 96 | ![grafana-app](./resource/grafana-panel.png) 97 | 98 | # 总结 99 | 100 | 以上演示了go-zero中基于prometheus+grafana服务指标监控的简单流程，生产环境中可以根据实际的场景做不同维度的监控分析。现在go-zero的监控指标主要还是针对http和rpc，这对于服务的整体监控显然还是不足的，比如容器资源的监控，依赖的mysql、redis等资源的监控，以及自定义的指标监控等等，go-zero在这方面后续还会持续优化。希望这篇文章能够给您带来帮助 -------------------------------------------------------------------------------- /cn/source.md: -------------------------------------------------------------------------------- 1 | # 相关源码 2 | * [demo源码](https://github.com/zeromicro/go-zero-demo) -------------------------------------------------------------------------------- /cn/summary.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | * [简介](README.md) 4 | * [阅读须知](tips.md) 5 | * [关于我们](about-us.md) 6 | * [加入我们](join-us.md) 7 | * [概念介绍](concept-introduction.md) 8 | * [快速开发](quick-start.md) 9 | * [单体服务](monolithic-service.md) 10 | * [微服务](micro-service.md) 11 | * [框架设计](framework-design.md) 12 | * [go-zero设计理念](go-zero-design.md) 13 | * [go-zero特点](go-zero-features.md) 14 | * [api语法介绍](api-grammar.md) 15 | * [api目录结构](api-dir.md) 16 | * [rpc目录结构](rpc-dir.md) 17 | * [项目开发](project-dev.md) 18 | * [准备工作](prepare.md) 19 | * [golang安装](golang-install.md) 20 | * [go module配置](gomod-config.md) 21 | * [goctl安装](goctl-install.md) 22 | * [protoc&protoc-gen-go安装](protoc-install.md) 23 | * [其他](prepare-other.md) 24 | * [开发规范](dev-specification.md) 25 | * [命名规范](naming-spec.md) 26 | * [路由规范](route-naming-spec.md) 27 | * [编码规范](coding-spec.md) 28 | * [开发流程](dev-flow.md) 29 | * [配置介绍](config-introduction.md) 30 | * [api配置](api-config.md) 31 | * [rpc配置](rpc-config.md) 32 | * [业务开发](business-dev.md) 33 | * [目录拆分](service-design.md) 34 | * [model生成](model-gen.md) 35 | * [api文件编写](api-coding.md) 36 | * [业务编码](business-coding.md) 37 | * [jwt鉴权](jwt.md) 38 | * [中间件使用](middleware.md) 39 | * [rpc服务编写与调用](rpc-call.md) 40 | * [错误处理](error-handle.md) 41 | * [CI/CD](ci-cd.md) 42 | * [服务部署](service-deployment.md) 43 | * [日志收集](log-collection.md) 44 | * [链路追踪](trace.md) 45 | * [服务监控](service-monitor.md) 46 | * [Goctl](goctl.md) 47 | * [命令大全](goctl-commands.md) 48 | * [api命令](goctl-api.md) 49 | * [rpc命令](goctl-rpc.md) 50 | * [model命令](goctl-model.md) 51 | * [plugin命令](goctl-plugin.md) 52 | * [其他命令](goctl-other.md) 53 | * [模板管理](template-manage.md) 54 | * [模板操作](template-cmd.md) 55 | * [自定义模板](template.md) 56 | * [组件中心](component-center.md) 57 | * [logx](logx.md) 58 | * [bloom](bloom.md) 59 | * [executors](executors.md) 60 | * [fx](fx.md) 61 | * [mysql](mysql.md) 62 | * [redis-lock](redis-lock.md) 63 | * [periodlimit](periodlimit.md) 64 | * [tokenlimit](tokenlimit.md) 65 | * [TimingWheel](timing-wheel.md) 66 | * [工具中心](tool-center.md) 67 | * [intellij插件](intellij.md) 68 | * [vscode插件](vscode.md) 69 | * [插件中心](plugin-center.md) 70 | * [学习资源](learning-resource.md) 71 | * [公众号](wechat.md) 72 | * [Go夜读](goreading.md) 73 | * [Go开源说](gotalk.md) 74 | * [开发实践](practise.md) 75 | * [go-zero缓存设计之持久层缓存](redis-cache.md) 76 | * [go-zero缓存设计之业务层缓存](buiness-cache.md) 77 | * [go-zero分布式定时任务](go-queue.md) 78 | * [我是如何用go-zero 实现一个中台系统](datacenter.md) 79 | * [流数据处理利器](stream.md) 80 | * [10月3日线上交流问题汇总](online-exchange.md) 81 | * [贡献人员](contributor.md) 82 | * [文档贡献](doc-contibute.md) 83 | * [常见错误处理](error.md) 84 | * [FAQ](faq.md) 85 | * [相关源码](source.md) 86 | 87 | -------------------------------------------------------------------------------- /cn/template-cmd.md: -------------------------------------------------------------------------------- 1 | # 模板操作 2 | 3 | 模板（Template）是数据驱动生成的基础，所有的代码（rest api、rpc、model、docker、kube）生成都会依赖模板， 4 | 默认情况下，模板生成器会选择内存中的模板进行生成，而对于有模板修改需求的开发者来讲，则需要将模板进行落盘， 5 | 从而进行模板修改，在下次代码生成时会加载指定路径下的模板进行生成。 6 | 7 | ## 使用帮助 8 | ```text 9 | NAME: 10 | goctl template - template operation 11 | 12 | USAGE: 13 | goctl template command [command options] [arguments...] 14 | 15 | COMMANDS: 16 | init initialize the all templates(force update) 17 | clean clean the all cache templates 18 | update update template of the target category to the latest 19 | revert revert the target template to the latest 20 | 21 | OPTIONS: 22 | --help, -h show help 23 | ``` 24 | 25 | ## 模板初始化 26 | ```text 27 | NAME: 28 | goctl template init - initialize the all templates(force update) 29 | 30 | USAGE: 31 | goctl template init [command options] [arguments...] 32 | 33 | OPTIONS: 34 | --home value the goctl home path of the template 35 | ``` 36 | 37 | ## 清除模板 38 | ```text 39 | NAME: 40 | goctl template clean - clean the all cache templates 41 | 42 | USAGE: 43 | goctl template clean [command options] [arguments...] 44 | 45 | OPTIONS: 46 | --home value the goctl home path of the template 47 | ``` 48 | 49 | ## 回滚指定分类模板 50 | ```text 51 | NAME: 52 | goctl template update - update template of the target category to the latest 53 | 54 | USAGE: 55 | goctl template update [command options] [arguments...] 56 | 57 | OPTIONS: 58 | --category value, -c value the category of template, enum [api,rpc,model,docker,kube] 59 | --home value the goctl home path of the template 60 | ``` 61 | 62 | ## 回滚模板 63 | ```text 64 | NAME: 65 | goctl template revert - revert the target template to the latest 66 | 67 | USAGE: 68 | goctl template revert [command options] [arguments...] 69 | 70 | OPTIONS: 71 | --category value, -c value the category of template, enum [api,rpc,model,docker,kube] 72 | --name value, -n value the target file name of template 73 | --home value the goctl home path of the template 74 | ``` 75 | 76 | > [!TIP] 77 | > 78 | > `--home` 指定模板存储路径 79 | 80 | ## 模板加载 81 | 82 | 在代码生成时可以通过`--home`来指定模板所在文件夹，目前已支持指定模板目录的命令有： 83 | 84 | - `goctl api go` 详情可以通过`goctl api go --help`查看帮助 85 | - `goctl docker` 详情可以通过`goctl docker --help`查看帮助 86 | - `goctl kube` 详情可以通过`goctl kube --help`查看帮助 87 | - `goctl rpc new` 详情可以通过`goctl rpc new --help`查看帮助 88 | - `goctl rpc proto` 详情可以通过`goctl rpc proto --help`查看帮助 89 | - `goctl model mysql ddl` 详情可以通过`goctl model mysql ddl --help`查看帮助 90 | - `goctl model mysql datasource` 详情可以通过`goctl model mysql datasource --help`查看帮助 91 | - `goctl model postgresql datasource` 详情可以通过`goctl model mysql datasource --help`查看帮助 92 | - `goctl model mongo` 详情可以通过`goctl model mongo --help`查看帮助 93 | 94 | 默认情况（在不指定`--home`）会从`$HOME/.goctl`目录下读取。 95 | 96 | ## 使用示例 97 | * 初始化模板到指定`$HOME/template`目录下 98 | ```text 99 | $ goctl template init --home $HOME/template 100 | ``` 101 | 102 | ```text 103 | Templates are generated in /Users/anqiansong/template, edit on your risk! 104 | ``` 105 | 106 | * 使用`$HOME/template`模板进行greet rpc生成 107 | ```text 108 | $ goctl rpc new greet --home $HOME/template 109 | ``` 110 | 111 | ```text 112 | Done 113 | ``` -------------------------------------------------------------------------------- /cn/template-manage.md: -------------------------------------------------------------------------------- 1 | # 模板管理 2 | 3 | - [模板操作](template-cmd.md) 4 | - [自定义模板](template-manage.md) -------------------------------------------------------------------------------- /cn/template.md: -------------------------------------------------------------------------------- 1 | # 模板修改 2 | 3 | ## 场景 4 | 实现统一格式的body响应，格式如下： 5 | ```json 6 | { 7 | "code": 0, 8 | "msg": "OK", 9 | "data": {} // ① 10 | } 11 | ``` 12 | 13 | ① 实际响应数据 14 | 15 | > [!TIP] 16 | > `go-zero`生成的代码没有对其进行处理 17 | ## 准备工作 18 | 我们提前在`module`为`greet`的工程下的`response`包中写一个`Response`方法，目录树类似如下： 19 | ```text 20 | greet 21 | ├── reponse 22 | │   └── response.go 23 | └── xxx... 24 | ``` 25 | 26 | 代码如下 27 | ```go 28 | package reponse 29 | 30 | import ( 31 | "net/http" 32 | 33 | "github.com/tal-tech/go-zero/rest/httpx" 34 | ) 35 | 36 | type Body struct { 37 | Code int `json:"code"` 38 | Msg string `json:"msg"` 39 | Data interface{} `json:"data,omitempty"` 40 | } 41 | 42 | func Response(w http.ResponseWriter, resp interface{}, err error) { 43 | var body Body 44 | if err != nil { 45 | body.Code = -1 46 | body.Msg = err.Error() 47 | } else { 48 | body.Msg = "OK" 49 | body.Data = resp 50 | } 51 | httpx.OkJson(w, body) 52 | } 53 | ``` 54 | 55 | ## 修改`handler`模板 56 | ```shell 57 | $ vim ~/.goctl/api/handler.tpl 58 | ``` 59 | 将模板替换为以下内容 60 | ```go 61 | package handler 62 | 63 | import ( 64 | "net/http" 65 | "greet/response"// ① 66 | 67 | {{.ImportPackages}} 68 | ) 69 | 70 | func {{.HandlerName}}(ctx *svc.ServiceContext) http.HandlerFunc { 71 | return func(w http.ResponseWriter, r *http.Request) { 72 | {{if .HasRequest}}var req types.{{.RequestType}} 73 | if err := httpx.Parse(r, &req); err != nil { 74 | httpx.Error(w, err) 75 | return 76 | }{{end}} 77 | 78 | l := logic.New{{.LogicType}}(r.Context(), ctx) 79 | {{if .HasResp}}resp, {{end}}err := l.{{.Call}}({{if .HasRequest}}req{{end}}) 80 | {{if .HasResp}}reponse.Response(w, resp, err){{else}}reponse.Response(w, nil, err){{end}}//② 81 | 82 | } 83 | } 84 | ``` 85 | 86 | ① 替换为你真实的`response`包名，仅供参考 87 | 88 | ② 自定义模板内容 89 | 90 | > [!TIP] 91 | > 92 | > 1.如果本地没有`~/.goctl/api/handler.tpl`文件，可以通过模板初始化命令`goctl template init`进行初始化 93 | 94 | ## 修改模板前后对比 95 | * 修改前 96 | ```go 97 | func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc { 98 | return func(w http.ResponseWriter, r *http.Request) { 99 | var req types.Request 100 | if err := httpx.Parse(r, &req); err != nil { 101 | httpx.Error(w, err) 102 | return 103 | } 104 | 105 | l := logic.NewGreetLogic(r.Context(), ctx) 106 | resp, err := l.Greet(req) 107 | // 以下内容将被自定义模板替换 108 | if err != nil { 109 | httpx.Error(w, err) 110 | } else { 111 | httpx.OkJson(w, resp) 112 | } 113 | } 114 | } 115 | ``` 116 | * 修改后 117 | ```go 118 | func GreetHandler(ctx *svc.ServiceContext) http.HandlerFunc { 119 | return func(w http.ResponseWriter, r *http.Request) { 120 | var req types.Request 121 | if err := httpx.Parse(r, &req); err != nil { 122 | httpx.Error(w, err) 123 | return 124 | } 125 | 126 | l := logic.NewGreetLogic(r.Context(), ctx) 127 | resp, err := l.Greet(req) 128 | reponse.Response(w, resp, err) 129 | } 130 | } 131 | ``` 132 | 133 | ## 修改模板前后响应体对比 134 | 135 | * 修改前 136 | ```json 137 | { 138 | "message": "Hello go-zero!" 139 | } 140 | ``` 141 | 142 | * 修改后 143 | ```json 144 | { 145 | "code": 0, 146 | "msg": "OK", 147 | "data": { 148 | "message": "Hello go-zero!" 149 | } 150 | } 151 | ``` 152 | 153 | # 总结 154 | 本文档仅对http相应为例讲述了自定义模板的流程，除此之外，自定义模板的场景还有： 155 | * model 层添加kmq 156 | * model 层生成待有效期option的model实例 157 | * http自定义相应格式 158 | ... 159 | -------------------------------------------------------------------------------- /cn/tips.md: -------------------------------------------------------------------------------- 1 | # 阅读须知 2 | 3 | 本文档从快速入门，详细项目开发流程，go-zero服务设计思想，goctl工具的使用等维度进行了介绍， 4 | 对于刚刚接触go或go-zero的同学需要把这些篇幅都看完才能有所了解，因此有些费力，这里建议大家阅读的方法。 5 | * 保持耐心跟着文档目录进行，文档是按照从简单到深入的渐进式过程编写的。 6 | * 在遇到问题或错误时，请一定记住多查[FAQ](faq.md)。 7 | -------------------------------------------------------------------------------- /cn/tool-center.md: -------------------------------------------------------------------------------- 1 | # 工具中心 2 | 在go-zero中，提供了很多提高工程效率的工具，如api，rpc生成，在此基础之上，api文件的编写就显得那么的无力， 3 | 因为缺少了高亮，代码提示，模板生成等，本节将带你了解go-zero是怎么解决这些难题的，本节包含以下小节： 4 | * [intellij插件](intellij.md) 5 | * [vscode插件](vscode.md) -------------------------------------------------------------------------------- /cn/vscode.md: -------------------------------------------------------------------------------- 1 | # vs code 插件 2 | 该插件可以安装在 1.46.0+ 版本的 Visual Studio Code 上，首先请确保你的 Visual Studio Code 版本符合要求，并已安装 goctl 命令行工具。如果尚未安装 Visual Studio Code，请安装并打开 Visual Studio Code。 导航到“扩展”窗格，搜索 goctl 并安装此扩展（发布者ID为 “xiaoxin-technology.goctl”）。 3 | 4 | Visual Studio Code 扩展使用请参考[这里](https://code.visualstudio.com/docs/editor/extension-gallery)。 5 | 6 | ## 功能列表 7 | 8 | 已实现功能 9 | 10 | * 语法高亮 11 | * 跳转到定义/引用 12 | * 代码格式化 13 | * 代码块提示 14 | 15 | 未实现功能: 16 | 17 | * 语法错误检查 18 | * 跨文件代码跳转 19 | * goctl 命令行调用 20 | 21 | ### 语法高亮 22 | 23 | ### 代码跳转 24 | 25 | ![jump](./resource/jump.gif) 26 | 27 | ### 代码格式化 28 | 29 | 调用 goctl 命令行格式化工具，使用前请确认 goctl 已加入 `$PATH` 且有可执行权限 30 | 31 | ### 代码块提示 32 | 33 | #### info 代码块 34 | 35 | ![info](./resource/info.gif) 36 | 37 | #### type 代码块 38 | 39 | ![type](./resource/type.gif) 40 | 41 | #### service 代码块 42 | 43 | ![type](./resource/service.gif) 44 | 45 | #### handler 代码块 46 | 47 | ![type](./resource/handler.gif) 48 | -------------------------------------------------------------------------------- /cn/wechat.md: -------------------------------------------------------------------------------- 1 | # 公众号 2 | 微服务实战是go-zero的官方公众号，在这里会发布最新的go-zero最佳实践，同步go夜读、go开源说、GopherChina、腾讯云开发者大会等多渠道关于go-zero的最新技术和资讯。 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
公众号名称公众号作者公众号二维码
微服务实战kevwan微服务实践
16 | 17 | # 干货 18 | 这里列举一些干货，想要收获更多go-zero最佳实践干货，可以关注公众号获取最新动态。 19 | * [《一文读懂云原生 go-zero 微服务框架》](https://mp.weixin.qq.com/s/gszj3-fwfcof5Tt2Th4dFA) 20 | * [《你还在手撕微服务？快试试 go-zero 的微服务自动生成》](https://mp.weixin.qq.com/s/Qvi-g3obgD_FVJ7CK3O56w) 21 | * [《最简单的Go Dockerfile编写姿势，没有之一！》](https://mp.weixin.qq.com/s/VLBiIbZStKhb7uth1ndgQQ) 22 | * [《通过MapReduce降低服务响应时间》](https://mp.weixin.qq.com/s/yxXAIK1eC_X22DH4ssZSag) 23 | * [《微服务过载保护原理与实战](https://mp.weixin.qq.com/s/CWzf6CY2R12Xd-rIYVvdPQ) 24 | * [《最简单的 K8S 部署文件编写姿势，没有之一！》](https://mp.weixin.qq.com/s/1GOMxlI8ocOL3U_I2TKPzQ) 25 | * [《go-zero 如何应对海量定时/延迟任务？》](https://mp.weixin.qq.com/s/CiZ5SpuT-VN8V9wil8_iGg) 26 | * [《go-zero 如何扛住流量冲击（一）》](https://mp.weixin.qq.com/s/xnJIm3asMncBfbtXo22sZw) 27 | * [《服务自适应降载保护设计》](https://mp.weixin.qq.com/s/cgjCL59e3CDWhsxzwkuKBg) -------------------------------------------------------------------------------- /en/about-us.md: -------------------------------------------------------------------------------- 1 | # About Us 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | ## Go-Zero 7 | 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. 8 | 9 | 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. 10 | 11 | ## Go-Zero's Author 12 | [kevwan](https://github.com/kevwan) 13 | 14 | **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. 15 | 16 | ## Go-Zero Members 17 | As of February 2021, go-zero currently has 30 team developers and 50+ community members. 18 | 19 | ## Go-Zero Community 20 | 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. 21 | 22 | -------------------------------------------------------------------------------- /en/api-coding.md: -------------------------------------------------------------------------------- 1 | # API File Coding 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | ## Create file 7 | ```shell 8 | $ vim service/user/cmd/api/user.api 9 | ``` 10 | ```text 11 | type ( 12 | LoginReq { 13 | Username string `json:"username"` 14 | Password string `json:"password"` 15 | } 16 | 17 | LoginReply { 18 | Id int64 `json:"id"` 19 | Name string `json:"name"` 20 | Gender string `json:"gender"` 21 | AccessToken string `json:"accessToken"` 22 | AccessExpire int64 `json:"accessExpire"` 23 | RefreshAfter int64 `json:"refreshAfter"` 24 | } 25 | ) 26 | 27 | service user-api { 28 | @handler login 29 | post /user/login (LoginReq) returns (LoginReply) 30 | } 31 | ``` 32 | ## Generate api service 33 | ### By goctl executable file 34 | 35 | ```shell 36 | $ cd book/service/user/cmd/api 37 | $ goctl api go -api user.api -dir . 38 | ``` 39 | ```text 40 | Done. 41 | ``` 42 | 43 | ### By Intellij Plugin 44 | 45 | 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. 46 | 47 | ![ApiGeneration](https://zeromicro.github.io/go-zero-pages/resource/goctl-api.png) 48 | ![ApiGenerationDirectorySelection](https://zeromicro.github.io/go-zero-pages/resource/goctl-api-select.png) 49 | 50 | ### By Keymap 51 | 52 | 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. 53 | 54 | # Guess you wants 55 | * [API IDL](api-grammar.md) 56 | * [API Commands](goctl-api.md) 57 | * [API Directory Structure](api-dir.md) -------------------------------------------------------------------------------- /en/api-dir.md: -------------------------------------------------------------------------------- 1 | # API directory introduction 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | ```text 7 | . 8 | ├── etc 9 | │ └── greet-api.yaml // yaml configuration file 10 | ├── go.mod // go module file 11 | ├── greet.api // api interface description language file 12 | ├── greet.go // main function entry 13 | └── internal 14 | ├── config 15 | │ └── config.go // configuration declaration type 16 | ├── handler // routing and handler forwarding 17 | │ ├── greethandler.go 18 | │ └── routes.go 19 | ├── logic // business logic 20 | │ └── greetlogic.go 21 | ├── middleware // middleware file 22 | │ └── greetmiddleware.go 23 | ├── svc // the resource pool that logic depends on 24 | │ └── servicecontext.go 25 | └── types // The struct of request and response is automatically generated according to the api, and editing is not recommended 26 | └── types.go 27 | ``` -------------------------------------------------------------------------------- /en/bloom.md: -------------------------------------------------------------------------------- 1 | # bloom 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | The go-zero microservice framework provides many out-of-the-box tools. 7 | Good tools can not only improve the performance of the service, 8 | but also improve the robustness of the code to avoid errors, 9 | and realize the uniformity of the code style for others to read, etc. 10 | A series of articles will respectively introduce the use of tools in the go-zero framework and their implementation principles. 11 | 12 | ## Bloom filter [bloom](https://github.com/tal-tech/go-zero/blob/master/core/bloom/bloom.go) 13 | When doing server development, I believe you have heard of Bloom filters, 14 | you can judge whether a certain element is in the collection, 15 | because there are certain misjudgments and delete complex problems, 16 | the general usage scenario is: to prevent cache breakdown (to prevent malicious Attacks), 17 | spam filtering, cache digests, model detectors, etc., 18 | to determine whether there is a row of data to reduce disk access and improve service access performance. 19 | The simple cache package bloom.bloom provided by go-zero, the simple way to use it is as follows. 20 | 21 | ```go 22 | // Initialize redisBitSet 23 | store := redis.NewRedis("redis 地址", redis.NodeType) 24 | // Declare a bitSet, key="test_key" name and bits are 1024 bits 25 | bitSet := newRedisBitSet(store, "test_key", 1024) 26 | // Determine whether the 0th bit exists 27 | isSetBefore, err := bitSet.check([]uint{0}) 28 | 29 | // Set the 512th bit to 1 30 | err = bitSet.set([]uint{512}) 31 | // Expires in 3600 seconds 32 | err = bitSet.expire(3600) 33 | 34 | // Delete the bitSet 35 | err = bitSet.del() 36 | ``` 37 | 38 | 39 | Bloom briefly introduced the use of the most basic redis bitset. The following is the real bloom implementation. 40 | 41 | Position the element hash 42 | 43 | ```go 44 | // The element is hashed 14 times (const maps=14), and byte (0-13) is appended to the element each time, and then the hash is performed. 45 | // Take the modulo of locations[0-13], and finally return to locations. 46 | func (f *BloomFilter) getLocations(data []byte) []uint { 47 | locations := make([]uint, maps) 48 | for i := uint(0); i < maps; i++ { 49 | hashValue := hash.Hash(append(data, byte(i))) 50 | locations[i] = uint(hashValue % uint64(f.bits)) 51 | } 52 | 53 | return locations 54 | } 55 | ``` 56 | 57 | 58 | Add elements to bloom 59 | ```go 60 | // We can find that the add method uses the set methods of getLocations and bitSet. 61 | // We hash the elements into uint slices of length 14, and then perform the set operation and store them in the bitSet of redis. 62 | func (f *BloomFilter) Add(data []byte) error { 63 | locations := f.getLocations(data) 64 | err := f.bitSet.set(locations) 65 | if err != nil { 66 | return err 67 | } 68 | return nil 69 | } 70 | ``` 71 | 72 | 73 | Check if there is an element in bloom 74 | ```go 75 | // We can find that the Exists method uses the check method of getLocations and bitSet 76 | // We hash the elements into uint slices of length 14, and then perform bitSet check verification, return true if it exists, false if it does not exist or if the check fails 77 | func (f *BloomFilter) Exists(data []byte) (bool, error) { 78 | locations := f.getLocations(data) 79 | isSet, err := f.bitSet.check(locations) 80 | if err != nil { 81 | return false, err 82 | } 83 | if !isSet { 84 | return false, nil 85 | } 86 | 87 | return true, nil 88 | } 89 | ``` 90 | 91 | This section mainly introduces the `core.bloom` tool in the go-zero framework, which is very practical in actual projects. Good use of tools is very helpful to improve service performance and development efficiency. I hope this article can bring you some gains. -------------------------------------------------------------------------------- /en/business-dev.md: -------------------------------------------------------------------------------- 1 | # Business development 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | In this chapter, we use a simple example to demonstrate some basic functions in go-zero. This section will contain the following subsections: 7 | * [Directory Structure](service-design.md) 8 | * [Model Generation](model-gen.md) 9 | * [API Coding](api-coding.md) 10 | * [Business Coding](business-coding.md) 11 | * [JWT](jwt.md) 12 | * [Middleware](middleware.md) 13 | * [RPC Implement & Call](rpc-call.md) 14 | * [Error Handling](error-handle.md) 15 | 16 | ## Demo project download 17 | Before officially entering the follow-up document description, you can pay attention to the source code here, and we will perform a progressive demonstration of the function based on this source code. 18 | Instead of starting from 0 completely, if you come from the [Quick Start](quick-start.md) chapter, this source code structure is not a problem for you. 19 | 20 | Click Here to download Demo project 21 | 22 | ## Demonstration project description 23 | 24 | ### Scenes 25 | The programmer Xiao Ming needs to borrow a copy of "Journey to the West". When there is no online library management system, he goes to the front desk of the library to consult with the librarian every day. 26 | * Xiao Ming: Hello, do you still have the book "Journey to the West" today? 27 | * Administrator: No more, let's check again tomorrow. 28 | 29 | One day later, Xiao Ming came to the library again and asked: 30 | * Xiao Ming: Hello, do you still have the book "Journey to the West" today? 31 | * Administrator: No, you can check again in two days. 32 | 33 | After many repetitions in this way, Xiao Ming was also in vain and wasted a lot of time on the way back and forth, so he finally couldn't stand the backward library management system. 34 | He decided to build a book review system by himself. 35 | 36 | ### Expected achievement 37 | * User login: 38 | Rely on existing student system data to log in 39 | * Book search: 40 | Search for books based on book keywords and query the remaining number of books. 41 | 42 | ### System analysis 43 | 44 | #### Service design 45 | * user 46 | * api: provides user login protocol 47 | * rpc: for search service to access user data 48 | * search 49 | * api: provide book query agreement 50 | 51 | > [!TIP] 52 | > Although this tiny book borrowing query system is small, it does not fit the business scenario in practice, but only the above two functions have already met our demonstration of the go-zero api/rpc scenario. 53 | > In order to satisfy the richer go-zero function demonstration in the future, business insertion, that is, related function descriptions, will be carried out in the document. Here only one scene is used for introduction. 54 | > 55 | > NOTE: Please create the sql statement in the user into the db by yourself, see [prepare](prepare.md) for more preparation work 56 | > 57 | > Add some preset user data to the database for later use. For the sake of space, the demonstration project does not demonstrate the operation of inserting data in detail. 58 | 59 | 60 | # Reference preset data 61 | ```sql 62 | INSERT INTO `user` (number,name,password,gender)values ('666','xiaoming','123456','male'); 63 | ``` -------------------------------------------------------------------------------- /en/ci-cd.md: -------------------------------------------------------------------------------- 1 | # CI/CD 2 | > [!TIP] 3 | > 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) 4 | 5 | 6 | > In software engineering, CI/CD or CICD generally refers to the combined practices of continuous integration and either continuous delivery or continuous deployment. 7 | > 8 | > ——[Wikipedia](https://zh.wikipedia.org/wiki/CI/CD) 9 | 10 | 11 | ![cd-cd](./resource/ci-cd.png) 12 | 13 | ## What can CI do? 14 | 15 | > In modern application development, the goal is to have multiple developers working simultaneously on different features of the same app. However, if an organization is set up to merge all branching source code together on one day (known as “merge day”), the resulting work can be tedious, manual, and time-intensive. That’s because when a developer working in isolation makes a change to an application, there’s a chance it will conflict with different changes being simultaneously made by other developers. This problem can be further compounded if each developer has customized their own local integrated development environment (IDE), rather than the team agreeing on one cloud-based IDE. 16 | 17 | > ——[Continuous integration](https://www.redhat.com/en/topics/devops/what-is-ci-cd) 18 | 19 | From a conceptual point of view, CI/CD includes the deployment process. Here, we will put the deployment (CD) in a separate section [Service Deployment](service-deployment.md), 20 | This section uses gitlab to do a simple CI (Run Unit Test) demonstration. 21 | 22 | ## Gitlab CI 23 | Gitlab CI/CD is a built-in software development tool of Gitlab, providing 24 | * Continuous Integration (CI) 25 | * Continuous Delivery (CD) 26 | * Continuous deployment (CD) 27 | 28 | ## Prepare 29 | * gitlab installation 30 | * git installation 31 | * gitlab runner installation 32 | 33 | ## Enable Gitlab CI 34 | * Upload code 35 | * Create a new warehouse `go-zero-demo` in gitlab 36 | * Upload the local code to the `go-zero-demo` warehouse 37 | * Create a `.gitlab-ci.yaml` file in the project root directory. Through this file, a pipeline can be created, which will be run when there is a content change in the code repository. The pipeline is run in sequence by one or more. 38 | Each stage can contain one or more jobs running in parallel. 39 | * Add CI content (for reference only) 40 | 41 | ```yaml 42 | stages: 43 | - analysis 44 | 45 | analysis: 46 | stage: analysis 47 | image: golang 48 | script: 49 | - go version && go env 50 | - go test -short $(go list ./...) | grep -v "no test" 51 | ``` 52 | 53 | > [!TIP] 54 | > The above CI is a simple demonstration. For detailed gitlab CI, please refer to the official gitlab documentation for richer CI integration. 55 | 56 | 57 | # Reference 58 | * [CI/CD Wikipedia](https://zh.wikipedia.org/wiki/CI/CD) 59 | * [Continuous integration](https://www.redhat.com/en/topics/devops/what-is-ci-cd) 60 | * [Gitlab CI](https://docs.gitlab.com/ee/ci/) -------------------------------------------------------------------------------- /en/coding-spec.md: -------------------------------------------------------------------------------- 1 | # Coding Rules 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | ## import 7 | * Single-line import is not recommended being wrapped in parentheses 8 | * Introduce in the order of `Official Package`, NEW LINE, `Project Package`, NEW LINE, `Third Party Dependent Package` 9 | ```go 10 | import ( 11 | "context" 12 | "string" 13 | 14 | "greet/user/internal/config" 15 | 16 | "google.golang.org/grpc" 17 | ) 18 | ``` 19 | 20 | ## Function returns 21 | * Object avoids non-pointer return 22 | * Follow the principle that if there is a normal value return, there must be no error, and if there is an error, there must be no normal value return. 23 | 24 | ## Error handling 25 | * An error must be handled, if it cannot be handled, it must be thrown. 26 | * Avoid underscore (_) receiving error 27 | 28 | ## Function body coding 29 | * It is recommended that a block end with a blank line, such as if, for, etc. 30 | ```go 31 | func main (){ 32 | if x==1{ 33 | // do something 34 | } 35 | 36 | fmt.println("xxx") 37 | } 38 | ``` 39 | * Blank line before return 40 | ```go 41 | func getUser(id string)(string,error){ 42 | .... 43 | 44 | return "xx",nil 45 | } 46 | ``` -------------------------------------------------------------------------------- /en/component-center.md: -------------------------------------------------------------------------------- 1 | # Components 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | The component center will include all components in the [go-zero](https://github.com/tal-tech/go-zero) core folder, 7 | Therefore, it will be relatively large, and this resource will continue to be updated, and everyone is welcome to contribute to the document. This section will contain the following directories (in order of document update time): 8 | 9 | * [logx](logx.md) 10 | * [bloom](bloom.md) 11 | * [executors](executors.md) 12 | * [fx](fx.md) 13 | * [mysql](mysql.md) 14 | * [redis-lock](redis-lock.md) 15 | * [periodlimit](periodlimit.md) 16 | * [tokenlimit](tokenlimit.md) 17 | * [TimingWheel](timing-wheel.md) 18 | -------------------------------------------------------------------------------- /en/concept-introduction.md: -------------------------------------------------------------------------------- 1 | # Concepts 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | 7 | ## go-zero 8 | 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. 9 | 10 | ## goctl 11 | An auxiliary tool designed to improve engineering efficiency and reduce error rates for developers. 12 | 13 | ## goctl plugins 14 | Refers to the peripheral binary resources centered on goctl, which can meet some personalized code generation requirements, such as the routing merge plug-in `goctl-go-compact` plug-in, 15 | The `goctl-swagger` plugin for generating swagger documents, the `goctl-php` plugin for generating the php caller, etc. 16 | 17 | ## intellij/vscode plugins 18 | A plug-in developed with goctl on the intellij series products, which replaces the goctl command line operation with the UI. 19 | 20 | ## api file 21 | An api file refers to a text file used to define and describe an api service. It ends with the .api suffix and contains IDL of the api syntax. 22 | 23 | ## goctl environment 24 | The goctl environment is the preparation environment before using goctl, including: 25 | * golang environment 26 | * protoc 27 | * protoc-gen-go plugin 28 | * go module | gopath 29 | 30 | ## go-zero-demo 31 | Go-zero-demo contains a large repository of all the source code in the document. When we write the demo in the future, we all create sub-projects under this project. 32 | Therefore, we need to create a large warehouse in advance `go-zero-demo`, and I put this warehouse in the home directory here. 33 | 34 | ```shell 35 | $ cd ~ 36 | $ mkdir go-zero-demo&&cd go-zero-demo 37 | $ go mod init go-zero-demo 38 | ``` 39 | 40 | 41 | # Reference 42 | * [go-zero](README.md) 43 | * [Goctl](goctl.md) 44 | * [Plugins](plugin-center.md) 45 | * [Tools](tool-center.md) 46 | * [API IDL](api-grammar.md) -------------------------------------------------------------------------------- /en/config-introduction.md: -------------------------------------------------------------------------------- 1 | # Configuration Introduction 2 | 3 | > [!TIP] 4 | > 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) 5 | 6 | Before officially using go-zero, let us first understand the configuration definitions of different service types in go-zero, and see what role each field in the configuration has. This section will contain the following subsections: 7 | * [API Configuration](api-config.md) 8 | * [RPC Configuration](rpc-config.md) -------------------------------------------------------------------------------- /en/dev-flow.md: -------------------------------------------------------------------------------- 1 | # Development Flow 2 | > [!TIP] 3 | > 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) 4 | 5 | The development process here is not a concept with our actual business development process. The definition here is limited to the use of go-zero, that is, the development details at the code level. 6 | 7 | ## Development Flow 8 | * Goctl environment preparation [1] 9 | * Database Design 10 | * Business development 11 | * New Construction 12 | * Create service catalog 13 | * Create service type (api/rpc/rmq/job/script) 14 | * Write api and proto files 15 | * Code generation 16 | * Generate database access layer code model 17 | * Configuration config, yaml change 18 | * Resource dependency filling (ServiceContext) 19 | * Add middleware 20 | * Business code filling 21 | * Error handling 22 | 23 | > [!TIP] 24 | > [1] [goctl environment](concept-introduction.md) 25 | 26 | ## Development Tools 27 | * Visual Studio Code 28 | * Goland (recommended) -------------------------------------------------------------------------------- /en/dev-specification.md: -------------------------------------------------------------------------------- 1 | # Development Rules 2 | > [!TIP] 3 | > 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) 4 | 5 | In actual business development, in addition to improving business development efficiency, shortening business development cycles, and ensuring high performance and high availability indicators for online business, good programming habits are also one of the basic qualities of a developer. In this chapter, 6 | 7 | We will introduce the coding standards in go-zero. This chapter is an optional chapter. The content is for communication and reference only. This chapter will explain from the following subsections: 8 | 9 | * [Naming Rules](naming-spec.md) 10 | * [Route Rules](route-naming-spec.md) 11 | * [Coding Rules](coding-spec.md) 12 | 13 | ## Three principles of development 14 | 15 | ### Clarity 16 | The author quoted a quote from `Hal Abelson and Gerald Sussman`: 17 | > Programs must be written for people to read, and only incidentally for machines to execute 18 | 19 | ### Simplicity 20 | > Simplicity is prerequisite for reliability 21 | 22 | `Edsger W. Dijkstra` believes that: the prerequisite for reliability is simplicity. We have all encountered in actual development. What is this code written and what it wants to accomplish. Developers don’t understand this code, so they don’t know. How to maintain, this brings complexity, the more complex the program, the harder it is to maintain, and the harder it is to maintain, the program becomes more and more complicated. Therefore, the first thing you should think of when encountering a program becoming complicated is - Refactoring, refactoring will redesign the program and make the program simple. 23 | 24 | ### Productivity） 25 | In the go-zero team, this topic has always been emphasized. The productivity of developers is not how many lines of code you have written and how many module developments you have completed, but we need to use various effective ways to take advantage of the limited Time to complete the development to maximize the efficiency, and the birth of Goctl was officially to increase productivity, 26 | Therefore, I very much agree with this development principle. 27 | 28 | -------------------------------------------------------------------------------- /en/doc-contibute.md: -------------------------------------------------------------------------------- 1 | # Document Contribute 2 | > [!TIP] 3 | > 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) 4 | 5 | ## How to contribute documents? 6 | Click the "Edit this page" button at the top to enter the file corresponding to the source code repository, and the developer will submit the modified (added) document in the form of pr, 7 | After we receive the pr, we will conduct a document review, and once the review is passed, the document can be updated. 8 | 9 | ![doc-edit](./resource/doc-edit.png) 10 | 11 | ## What documents can I contribute? 12 | * Documentation errors 13 | * The documentation is not standardized and incomplete 14 | * Go-zero application practice and experience 15 | * Component Center 16 | 17 | ## How soon will the document be updated after the document pr is passed? 18 | After pr accepts, github action will automatically build gitbook and release, so you can view the updated document 1-2 minutes after github action is successful. 19 | 20 | ## Documentation contribution notes 21 | * Error correction and improvement of the source document can directly write the original md file 22 | * The newly added component documents need to be typeset and easy to read, and the component documents need to be placed in the [Components](component-center.md) subdirectory 23 | * Go-zero application practice sharing can be directly placed in the [Development Practice](practise.md) subdirectory 24 | 25 | ## Directory structure specification 26 | * The directory structure should not be too deep, preferably no more than 3 levels 27 | * The component document needs to be attributed to [Component Center] (component-center.md), such as 28 | * [Development Practice](practise.md) 29 | * [logx](logx.md) 30 | * [bloom](bloom.md) 31 | * [executors](executors.md) 32 | * Your document directory name 33 | * Application practice needs to be attributed to [Development Practice](practise.md), such as 34 | * [Development Practice](practise.md) 35 | * [How do I use go-zero to implement a middle-office system] (datacenter.md) 36 | * [Stream data processing tool](stream.md) 37 | * [Summary of online communication issues on October 3](online-exchange.md 38 | * Your document directory name 39 | 40 | ## Development Practice Document Template 41 | ```markdown 42 | # Title 43 | 44 | > Author：The author name 45 | > 46 | > Original link： The original link 47 | 48 | some markdown content 49 | ``` 50 | 51 | # Guess you wants 52 | * [Join Us](join-us.md) 53 | * [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) 54 | 55 | -------------------------------------------------------------------------------- /en/error.md: -------------------------------------------------------------------------------- 1 | # Error 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Error reporting on Windows 6 | ```text 7 | A required privilege is not held by the client. 8 | ```text 9 | Solution: "Run as administrator" goctl will work. 10 | 11 | ## grpc error 12 | * Case 1 13 | ```text 14 | protoc-gen-go: unable to determine Go import path for "greet.proto" 15 | 16 | Please specify either: 17 | • a "go_package" option in the .proto source file, or 18 | • a "M" argument on the command line. 19 | 20 | See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information. 21 | 22 | --go_out: protoc-gen-go: Plugin failed with status code 1. 23 | 24 | ``` 25 | Solution: 26 | ```text 27 | go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2 28 | ``` 29 | 30 | ## protoc-gen-go installation failed 31 | ```text 32 | go get github.com/golang/protobuf/protoc-gen-go: module github.com/golang/protobuf/protoc-gen-go: Get "https://proxy.golang.org/github.com/golang/protobuf/protoc-gen-go/@v/list": dial tcp 216.58.200.49:443: i/o timeout 33 | ``` 34 | 35 | Please make sure `GOPROXY` has been set, see [Go Module Configuration](gomod-config.md) for GOPROXY setting 36 | 37 | ## api service failed to start 38 | ```text 39 | error: config file etc/user-api.yaml, error: type mismatch for field xx 40 | ``` 41 | 42 | Please confirm whether the configuration items in the `user-api.yaml` configuration file have been configured. If there are values, check whether the yaml configuration file conforms to the yaml format. 43 | 44 | ## command not found: goctl 45 | ``` 46 | command not found: goctl 47 | ``` 48 | Please make sure that goctl has been installed or whether goctl has been added to the environment variable -------------------------------------------------------------------------------- /en/framework-design.md: -------------------------------------------------------------------------------- 1 | # Framework Design 2 | > [!TIP] 3 | > 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) 4 | 5 | ![architechture](./resource/architechture.svg) 6 | 7 | This section will explain the design of go-zero framework from the go-zero design philosophy and the best practice catalog of go-zero services. This section will contain the following subsections: 8 | 9 | * [Go-Zero Design](go-zero-design.md) 10 | * [Go-Zero Features](go-zero-features.md) 11 | * [API IDL](api-grammar.md) 12 | * [API Directory Structure](api-dir.md) 13 | * [RPC Directory Structure](rpc-dir.md) 14 | -------------------------------------------------------------------------------- /en/go-zero-design.md: -------------------------------------------------------------------------------- 1 | # Go-Zero Design 2 | > [!TIP] 3 | > 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) 4 | 5 | For the design of the microservice framework, we expect that while ensuring the stability of microservices, we must also pay special attention to research and development efficiency. So at the beginning of the design, we have the following guidelines: 6 | 7 | * Keep it simple, first principle 8 | * Flexible design, fault-oriented programming 9 | * Tools are bigger than conventions and documents 10 | * High availability 11 | * High concurrency 12 | * Easy to expand 13 | * Friendly to business development, package complexity 14 | * There is only one way to constrain one thing -------------------------------------------------------------------------------- /en/go-zero-features.md: -------------------------------------------------------------------------------- 1 | # Go-Zero Features 2 | > [!TIP] 3 | > 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) 4 | 5 | go-zero is a web and rpc framework that integrates various engineering practices. It has the following main features: 6 | 7 | * Powerful tool support, as little code writing as possible 8 | * Minimalist interface 9 | * Fully compatible with net.http 10 | * Support middleware for easy expansion 11 | * High performance 12 | * Fault-oriented programming, flexible design 13 | * Built-in service discovery, load balancing 14 | * Built-in current limiting, fusing, load reduction, and automatic triggering, automatic recovery 15 | * API parameter automatic verification 16 | * Timeout cascade control 17 | * Automatic cache control 18 | * Link tracking, statistical alarm, etc. 19 | * High concurrency support, stably guaranteeing daily traffic peaks during the epidemic 20 | 21 | As shown in the figure below, we have ensured the high availability of the overall service from multiple levels: 22 | 23 | ![resilience](https://gitee.com/kevwan/static/raw/master/doc/images/resilience.jpg) -------------------------------------------------------------------------------- /en/goctl-api.md: -------------------------------------------------------------------------------- 1 | # API Commands 2 | > [!TIP] 3 | > 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) 4 | 5 | goctl api is one of the core modules in goctl. It can quickly generate an api service through the .api file with one click. If you just start a go-zero api demo project, 6 | You can complete an api service development and normal operation without even coding. In traditional api projects, we have to create directories at all levels, write structures, 7 | Define routing, add logic files, this series of operations, if calculated according to the business requirements of a protocol, it takes about 5 to 6 minutes for the entire coding to actually enter the writing of business logic. 8 | This does not consider the various errors that may occur during the writing process. With the increase of services and the increase of agreements, the time for this part of the preparation work will increase proportionally. 9 | The goctl api can completely replace you to do this part of the work, no matter how many agreements you have, in the end, it only takes less than 10 seconds to complete. 10 | 11 | > [!TIP] 12 | > The structure is written, and the route definition is replaced by api, so in general, it saves you the time of creating folders, adding various files and resource dependencies. 13 | 14 | ## API command description 15 | ```shell 16 | $ goctl api -h 17 | ``` 18 | ```text 19 | NAME: 20 | goctl api - generate api related files 21 | 22 | USAGE: 23 | goctl api command [command options] [arguments...] 24 | 25 | COMMANDS: 26 | new fast create api service 27 | format format api files 28 | validate validate api file 29 | doc generate doc files 30 | go generate go files for provided api in yaml file 31 | java generate java files for provided api in api file 32 | ts generate ts files for provided api in api file 33 | dart generate dart files for provided api in api file 34 | kt generate kotlin code for provided api file 35 | plugin custom file generator 36 | 37 | OPTIONS: 38 | -o value the output api file 39 | --help, -h show help 40 | ``` 41 | 42 | As you can see from the above, according to the different functions, the api contains a lot of self-commands and flags, let’s focus on it here 43 | The `go` subcommand, which function is to generate golang api services, let's take a look at the usage help through `goctl api go -h`: 44 | ```shell 45 | $ goctl api go -h 46 | ``` 47 | ```text 48 | NAME: 49 | goctl api go - generate go files for provided api in yaml file 50 | 51 | USAGE: 52 | goctl api go [command options] [arguments...] 53 | 54 | OPTIONS: 55 | --dir value the target dir 56 | --api value the api file 57 | --style value the file naming format, see [https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/readme.md] 58 | ``` 59 | 60 | * --dir: Code output directory 61 | * --api: Specify the api source file 62 | * --style: Specify the file name style of the generated code file, see for details [https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/readme.md](https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/readme.md) 63 | 64 | ## Usage example 65 | ```shell 66 | $ goctl api go -api user.api -dir . -style gozero 67 | ``` 68 | 69 | # Guess you wants 70 | * [API IDL](api-grammar.md) 71 | * [API Directory Structure](api-dir.md) -------------------------------------------------------------------------------- /en/goctl-install.md: -------------------------------------------------------------------------------- 1 | # Goctl Installation 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Foreword 6 | Goctl plays a very important role in the development of the go-zero project. It can effectively help developers greatly improve development efficiency, reduce code error rate, and shorten the workload of business development. For more introductions to Goctl, please read [Goctl Introduction ](goctl.md), 7 | 8 | Here we strongly recommend that you install it, because most of the follow-up demonstration examples will use goctl for demonstration. 9 | 10 | ## Install(mac&linux) 11 | * download&install 12 | ```shell 13 | GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl 14 | ``` 15 | * Environmental variable detection 16 | 17 | The compiled binary file downloaded by `go get` is located in the `$GOPATH/bin` directory. Make sure that `$GOPATH/bin` has been added to the environment variable. 18 | ```shell 19 | $ sudo vim /etc/paths 20 | ``` 21 | Add the following in the last line 22 | ```text 23 | $GOPATH/bin 24 | ``` 25 | > [!TIP] 26 | > `$GOPATH` is the filepath on your local machine 27 | 28 | * Installation result verification 29 | ```shell 30 | $ goctl -v 31 | ``` 32 | ```text 33 | goctl version 1.1.4 darwin/amd64 34 | ``` 35 | 36 | > [!TIP] 37 | > For windows users to add environment variables, please Google by yourself. 38 | -------------------------------------------------------------------------------- /en/goctl-plugin.md: -------------------------------------------------------------------------------- 1 | # Plugin Commands 2 | > [!TIP] 3 | > 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) 4 | 5 | Goctl supports custom plugins for api, so how do I customize a plugin? Let's take a look at an example of how to finally use it below. 6 | ```go 7 | $ goctl api plugin -p goctl-android="android -package com.tal" -api user.api -dir . 8 | ``` 9 | 10 | The above command can be broken down into the following steps: 11 | * goctl parsing api file 12 | * goctl passes the parsed structure ApiSpec and parameters to the goctl-android executable file 13 | * goctl-android customizes the generation logic according to the ApiSpec structure. 14 | 15 | The first part of this command goctl api plugin -p is a fixed parameter, goctl-android="android -package com.tal" is a plugin parameter, where goctl-android is the plugin binary file, and android -package com.tal is a custom parameter of the plugin , -Api user.api -dir. Is a common custom parameter for goctl. 16 | ## How to write a custom plug-in? 17 | A very simple custom plug-in demo is included in the go-zero framework. The code is as follows: 18 | ```go 19 | package main 20 | 21 | import ( 22 | "fmt" 23 | 24 | "github.com/tal-tech/go-zero/tools/goctl/plugin" 25 | ) 26 | 27 | func main() { 28 | plugin, err := plugin.NewPlugin() 29 | if err != nil { 30 | panic(err) 31 | } 32 | if plugin.Api != nil { 33 | fmt.Printf("api: %+v \n", plugin.Api) 34 | } 35 | fmt.Printf("dir: %s \n", plugin.Dir) 36 | fmt.Println("Enjoy anything you want.") 37 | } 38 | ``` 39 | 40 | `plugin, err := plugin.NewPlugin()` The function of this line of code is to parse the data passed from goctl, which contains the following parts: 41 | 42 | ```go 43 | type Plugin struct { 44 | Api *spec.ApiSpec 45 | Style string 46 | Dir string 47 | } 48 | ``` 49 | > [!TIP] 50 | > Api: defines the structure data of the api file 51 | > 52 | > Style: optional, it is used to control file naming conventions 53 | > 54 | > Dir: workDir 55 | 56 | 57 | Complete android plugin demo project based on plugin 58 | [https://github.com/zeromicro/goctl-android](https://github.com/zeromicro/goctl-android) 59 | 60 | # Guess you wants 61 | * [API Directory Structure](api-dir.md) 62 | * [API IDL](api-grammar.md) 63 | * [API Configuration](api-config.md) 64 | * [API Commands](goctl-api.md) -------------------------------------------------------------------------------- /en/goctl.md: -------------------------------------------------------------------------------- 1 | # Goctl 2 | > [!TIP] 3 | > 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) 4 | 5 | goctl is a code generation tool under the go-zero microservice framework. Using goctl can significantly improve development efficiency and allow developers to focus their time on business development. Its functions include: 6 | 7 | - api service generation 8 | - rpc service generation 9 | - model code generation 10 | - template management 11 | 12 | This section will contain the following: 13 | 14 | * [Commands & Flags](goctl-commands.md) 15 | * [API Commands](goctl-api.md) 16 | * [RPC Commands](goctl-rpc.md) 17 | * [Model Commands](goctl-model.md) 18 | * [Plugin Commands](goctl-plugin.md) 19 | * [More Commands](goctl-other.md) 20 | 21 | ## goctl？ 22 | Many people will pronounce `goctl` as `go-C-T-L`. This is a wrong way of thinking. You should refer to `go control` and pronounce `ɡō kənˈtrōl`. 23 | 24 | ## View version information 25 | ```shell 26 | $ goctl -v 27 | ``` 28 | 29 | If goctl is installed, it will output text information in the following format: 30 | 31 | ```text 32 | goctl version ${version} ${os}/${arch} 33 | ``` 34 | 35 | For example output: 36 | ```text 37 | goctl version 1.1.5 darwin/amd64 38 | ``` 39 | 40 | Version number description 41 | * version: goctl version number 42 | * os: Current operating system name 43 | * arch: Current system architecture name 44 | 45 | ## Install goctl 46 | 47 | ### The way one（go get） 48 | 49 | ```shell 50 | $ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/tal-tech/go-zero/tools/goctl 51 | ``` 52 | 53 | Use this command to install the goctl tool into the `$GOPATH/bin` directory 54 | 55 | ### The way two （fork and build） 56 | 57 | Pull a source code from the go-zero code repository `git@github.com:tal-techgo-zero.git`, enter the `toolsgoctl` directory to compile the goctl file, and then add it to the environment variable. 58 | 59 | After the installation is complete, execute `goctl -v`. If the version information is output, the installation is successful, for example: 60 | 61 | ```shell 62 | $ goctl -v 63 | 64 | goctl version 1.1.4 darwin/amd64 65 | ``` 66 | 67 | ## FAQ 68 | ``` 69 | command not found: goctl 70 | ``` 71 | Please make sure that goctl has been installed, or whether goctl has been correctly added to the environment variables of the current shell. 72 | -------------------------------------------------------------------------------- /en/golang-install.md: -------------------------------------------------------------------------------- 1 | # Golang Installation 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Forward 6 | To develop a golang program, the installation of its environment must be indispensable. Here we choose to take 1.15.1 as an example. 7 | 8 | ## Official document 9 | [https://golang.google.cn/doc/install](https://golang.google.cn/doc/install) 10 | 11 | ## Install Go on macOS 12 | 13 | * Download and install [Go for Mac](https://dl.google.com/go/go1.15.1.darwin-amd64.pkg) 14 | * Verify the installation result 15 | ```shell 16 | $ go version 17 | ``` 18 | ```text 19 | go version go1.15.1 darwin/amd64 20 | ``` 21 | ## Install Go on linux 22 | * Download [Go for Linux](https://golang.org/dl/go1.15.8.linux-amd64.tar.gz) 23 | * Unzip the compressed package to `/usr/local` 24 | ```shell 25 | $ tar -C /usr/local -xzf go1.15.8.linux-amd64.tar.gz 26 | ``` 27 | * Add `/usr/local/go/bin` to environment variables 28 | ```shell 29 | $ $HOME/.profile 30 | ``` 31 | ```shell 32 | export PATH=$PATH:/usr/local/go/bin 33 | ``` 34 | ```shell 35 | $ source $HOME/.profile 36 | ``` 37 | * Verify the installation result 38 | ```shell 39 | $ go version 40 | ``` 41 | ```text 42 | go version go1.15.1 linux/amd64 43 | ``` 44 | ## Install Go on windows 45 | * Download and install [Go for Windows](https://golang.org/dl/go1.15.8.windows-amd64.msi) 46 | * Verify the installation result 47 | ```shell 48 | $ go version 49 | ``` 50 | ```text 51 | go version go1.15.1 windows/amd64 52 | ``` 53 | 54 | ## More 55 | For more operating system installation, see [https://golang.org/dl/](https://golang.org/dl/) 56 | -------------------------------------------------------------------------------- /en/gomod-config.md: -------------------------------------------------------------------------------- 1 | # Go Module Configuration 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Introduction to Go Module 6 | > Modules are how Go manages dependencies.[1] 7 | 8 | That is, Go Module is a way for Golang to manage dependencies, similar to Maven in Java and Gradle in Android. 9 | 10 | ## Module configuration 11 | * Check the status of `GO111MODULE` 12 | ```shell 13 | $ go env GO111MODULE 14 | ``` 15 | ```text 16 | on 17 | ``` 18 | * Turn on `GO111MODULE`, if it is already turned on (that is, execute `go env GO111MODULE` and the result is `on`), please skip it. 19 | ```shell 20 | $ go env -w GO111MODULE="on" 21 | ``` 22 | * Set up `GOPROXY` 23 | ```shell 24 | $ go env -w GOPROXY=https://goproxy.cn 25 | ``` 26 | * Set up `GOMODCACHE` 27 | 28 | view `GOMODCACHE` 29 | ```shell 30 | $ go env GOMODCACHE 31 | ``` 32 | If the directory is not empty or `/dev/null`, please skip it. 33 | ```shell 34 | go env -w GOMODCACHE=$GOPATH/pkg/mod 35 | ``` 36 | 37 | 38 | # Reference 39 | [1] [Go Modules Reference](https://golang.google.cn/ref/mod) -------------------------------------------------------------------------------- /en/goreading.md: -------------------------------------------------------------------------------- 1 | # Night 2 | > [!TIP] 3 | > 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) 4 | 5 | * [2020-08-16 XiaoHeiBan go-zero microservice framework architecture design](https://talkgo.org/t/topic/729) 6 | * [2020-10-03 go-zero microservice framework and online communication](https://talkgo.org/t/topic/1070) 7 | * [In-process shared calls to prevent cache breakdown](https://talkgo.org/t/topic/968) 8 | * [Implement JWT authentication based on go-zero](https://talkgo.org/t/topic/1114) 9 | * [Goodbye go-micro! Enterprise project migration go-zero strategy (1)](https://talkgo.org/t/topic/1607) -------------------------------------------------------------------------------- /en/gotalk.md: -------------------------------------------------------------------------------- 1 | # OpenTalk 2 | > [!TIP] 3 | > 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) 4 | 5 | * [OpenTalk 4th - Go-Zero](https://www.bilibili.com/video/BV1Jy4y127Xu) -------------------------------------------------------------------------------- /en/join-us.md: -------------------------------------------------------------------------------- 1 | # Join Us 2 | > [!TIP] 3 | > 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) 4 | 5 | 6 | ## Summary 7 | go-zero 8 | 9 | [go-zero](https://github.com/tal-tech/go-zero) is based on the [MIT License](https://github.com/tal-tech/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. 10 | 11 | ## Contribution form 12 | * [Pull Request](https://github.com/tal-tech/go-zero/pulls) 13 | * [Issue](https://github.com/tal-tech/go-zero/issues) 14 | 15 | ## Contribution notes 16 | The code in go-zero's Pull request needs to meet certain specifications 17 | * For naming conventions, please read [naming conventions](naming-spec.md) 18 | * Mainly English annotations 19 | * Remark the functional characteristics when pr, the description needs to be clear and concise 20 | * Increase unit test coverage to 80%+ 21 | 22 | ## Pull Request（pr） 23 | * Enter [go-zero](https://github.com/tal-tech/go-zero) project, fork a copy of [go-zero](https://github.com/tal-tech/go-zero) Project to its own GitHub repository. 24 | * Go back to your GitHub homepage and find the `xx/go-zero` project, where xx is your username, such as `anqiansong/go-zero` 25 | 26 | ![fork](./resource/fork.png) 27 | * Clone the code to local 28 | 29 | ![clone](./resource/clone.png) 30 | * Develop code and push to your own GitHub repository 31 | * Enter the go-zero project in your own GitHub, click on the `[Pull requests]` on the floating layer to enter the Compare page. 32 | 33 | ![pr](./resource/new_pr.png) 34 | 35 | * `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: 36 | 37 | ![pr](./resource/compare.png) 38 | 39 | * Click `[Create pull request]` to realize the pr application 40 | * To confirm whether the pr submission is successful, enter [Pull requests](https://github.com/tal-tech/go-zero) of [go-zero](https://github.com/tal-tech/go-zero) /pulls) view, there should be a record of your own submission, the name is your branch name during development. 41 | 42 | ![pr record](./resource/pr_record.png) 43 | 44 | ## Issue 45 | In our community, many partners will actively feedback some problems encountered during the use of go-zero. 46 | Due to the large number of people in the community, although we will follow the community dynamics in real time, 47 | 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, 48 | 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. 49 | 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. 50 | You can also get the latest trend of go-zero here, and welcome everyone Come and actively participate in the discussion. 51 | 52 | ### How to issue 53 | * Click [here](https://github.com/tal-tech/go-zero/issues) to enter go-zero's Issue page or directly visit [https://github.com/tal-tech/go-zero/ issues](https://github.com/tal-tech/go-zero/issues) address 54 | * Click `[New issue]` in the upper right corner to create a new issue 55 | * Fill in the issue title and content 56 | * Click `【Submit new issue】` to submit an issue 57 | 58 | 59 | ## Reference 60 | 61 | * [Github Pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) -------------------------------------------------------------------------------- /en/learning-resource.md: -------------------------------------------------------------------------------- 1 | # Learning Resources 2 | > [!TIP] 3 | > 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) 4 | 5 | The latest learning resource channel of go-zero will be updated from time to time. Currently, the channels included are: 6 | * [Wechat](wechat.md) 7 | * [Night](goreading.md) 8 | * [OpenTalk](gotalk.md) -------------------------------------------------------------------------------- /en/model-gen.md: -------------------------------------------------------------------------------- 1 | # Model Generation 2 | > [!TIP] 3 | > 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) 4 | 5 | 6 | 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. 7 | 8 | ## Forward 9 | 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. 10 | 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. 11 | 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. 12 | 13 | ## Prepare 14 | Enter the demo project `book`, find the` user.sql` file under `user/model`, and execute the table creation in your own database. 15 | 16 | ## Code generation (with cache) 17 | ### The way one(ddl) 18 | Enter the `service/user/model` directory and execute the command 19 | ```shell 20 | $ cd service/user/model 21 | $ goctl model mysql ddl -src user.sql -dir . -c 22 | ``` 23 | ```text 24 | Done. 25 | ``` 26 | 27 | ### The way two(datasource) 28 | ```shell 29 | $ goctl model mysql datasource -url="$datasource" -table="user" -c -dir . 30 | ``` 31 | ```text 32 | Done. 33 | ``` 34 | > [!TIP] 35 | > `$datasource` is the database connection address 36 | 37 | ### The way three(intellij plugin) 38 | In Goland, right-click `user.sql`, enter and click `New`->`Go Zero`->`Model Code` to generate it, or open the `user.sql` file, 39 | Enter the editing area, use the shortcut key `Command+N` (for macOS) or `alt+insert` (for windows), select `Mode Code`. 40 | 41 | ![model generation](https://zeromicro.github.io/go-zero-pages/resource/intellij-model.png) 42 | 43 | > [!TIP] 44 | > The intellij plug-in generation needs to install the goctl plug-in, see [intellij plugin](intellij.md) for details 45 | 46 | ## Verify the generated model file 47 | view tree 48 | ```shell 49 | $ tree 50 | ``` 51 | ```text 52 | . 53 | ├── user.sql 54 | ├── usermodel.go 55 | └── vars.go 56 | ``` 57 | 58 | # Guess you wants 59 | [Model Commands](goctl-model.md) 60 | -------------------------------------------------------------------------------- /en/monolithic-service.md: -------------------------------------------------------------------------------- 1 | # Monolithic Service 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Forward 6 | Since go-zero integrates web/rpc, some friends in the community will ask me whether go-zero is positioned as a microservice framework. 7 | 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. 8 | 9 | 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. 10 | 11 | ## Create greet service 12 | ```shell 13 | $ cd ~/go-zero-demo 14 | $ goctl api new greet 15 | Done. 16 | ``` 17 | 18 | Take a look at the structure of the `greet` service 19 | ```shell 20 | $ cd greet 21 | $ tree 22 | ``` 23 | ```text 24 | . 25 | ├── etc 26 | │   └── greet-api.yaml 27 | ├── go.mod 28 | ├── greet.api 29 | ├── greet.go 30 | └── internal 31 | ├── config 32 | │   └── config.go 33 | ├── handler 34 | │   ├── greethandler.go 35 | │   └── routes.go 36 | ├── logic 37 | │   └── greetlogic.go 38 | ├── svc 39 | │   └── servicecontext.go 40 | └── types 41 | └── types.go 42 | ``` 43 | 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`. 44 | 45 | ## Write logic 46 | ```shell 47 | $ vim ~/go-zero-demo/greet/internal/logic/greetlogic.go 48 | ``` 49 | ```go 50 | func (l *GreetLogic) Greet(req types.Request) (*types.Response, error) { 51 | return &types.Response{ 52 | Message: "Hello go-zero", 53 | }, nil 54 | } 55 | ``` 56 | 57 | ## Start and access the service 58 | 59 | * Start service 60 | ```shell 61 | $ cd ~/go-zer-demo/greet 62 | $ go run greet.go -f etc/greet-api.yaml 63 | ``` 64 | ```text 65 | Starting server at 0.0.0.0:8888... 66 | ``` 67 | 68 | * Access service 69 | ```shell 70 | $ curl -i -X GET \ 71 | http://localhost:8888/from/you 72 | ``` 73 | 74 | ```text 75 | HTTP/1.1 200 OK 76 | Content-Type: application/json 77 | Date: Sun, 07 Feb 2021 04:31:25 GMT 78 | Content-Length: 27 79 | 80 | {"message":"Hello go-zero"} 81 | ``` 82 | 83 | # Source code 84 | [greet source code](https://github.com/zeromicro/go-zero-demo/tree/master/greet) 85 | 86 | # Guess you wants 87 | * [Goctl](goctl.md) 88 | * [API Directory Structure](api-dir.md) 89 | * [API IDL](api-grammar.md) 90 | * [API Configuration](api-config.md) 91 | * [Middleware](middleware.md) 92 | 93 | 94 | 95 | -------------------------------------------------------------------------------- /en/naming-spec.md: -------------------------------------------------------------------------------- 1 | # Naming Rules 2 | > [!TIP] 3 | > 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) 4 | 5 | In any language development, there are some naming conventions in the language field, good 6 | * Reduce code reading costs 7 | * Reduce maintenance difficulty 8 | * Reduce code complexity 9 | 10 | ## Specification suggestion 11 | In our actual development, many developers may transfer from one language to another language field. After switching to another language, 12 | We will all retain the programming habits of the old language. Here, what I suggest is that although some previous specifications of different languages may be the same, 13 | But we'd better be familiar with some official demos to gradually adapt to the programming specifications of the current language, rather than directly migrating the programming specifications of the original language. 14 | 15 | ## Naming guidelines 16 | * When the distance between the definition and the last use of the variable name is short, the short name looks better. 17 | * Variable naming should try to describe its content, not type 18 | * Constant naming should try to describe its value, not how to use this value 19 | * When encountering for, if and other loops or branches, single letter names are recommended to identify parameters and return values 20 | * It is recommended to use words to name method, interface, type, and package 21 | * The package name is also part of the naming, please use it as much as possible 22 | * Use a consistent naming style 23 | 24 | ## File naming guidelines 25 | * All lowercase 26 | * Avoid underscores (_) except for unit test 27 | * The file name should not be too long 28 | 29 | ## Variable naming convention reference 30 | * Initial lowercase 31 | * Hump naming 32 | * See the name to know the meaning, avoid pinyin instead of English 33 | * It is not recommended including an underscore (_) 34 | * It is not recommended including numbers 35 | 36 | **Scope of application** 37 | * Local variables 38 | * Function parameter output, input parameter 39 | 40 | ## Function and constant naming convention 41 | * Camel case naming 42 | * The first letter of the exported must be capitalized 43 | * The first letter must be lowercase if it cannot be exported 44 | * Avoid the combination of all uppercase and underscore (_) 45 | 46 | 47 | > [!TIP] 48 | > If it is a go-zero code contribution, you must strictly follow this naming convention 49 | 50 | 51 | # Reference 52 | * [Practical Go: Real world advice for writing maintainable Go programs](https://dave.cheney.net/practical-go/presentations/gophercon-singapore-2019.html#_simplicity) -------------------------------------------------------------------------------- /en/plugin-center.md: -------------------------------------------------------------------------------- 1 | # Plugins 2 | > [!TIP] 3 | > 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) 4 | 5 | The goctl api provides plugin commands to support the function extension of the api. When the functions in the goctl api do not satisfy your use, 6 | Or you need to extend goctl api function customization, then the plug-in function will be very suitable for developers to be self-sufficient, see for details 7 | [goctl plugin](goctl-plugin.md) 8 | 9 | ## Plugin resources 10 | * [goctl-go-compact](https://github.com/zeromicro/goctl-go-compact) 11 | Goctl's default route merges one file into one file 12 | * [goctl-swagger](https://github.com/zeromicro/goctl-swagger) 13 | Generate swagger documents through api files 14 | * [goctl-php](https://github.com/zeromicro/goctl-php) 15 | goctl-php is a plug-in based on goctl, used to generate php call end (server end) http server request code 16 | 17 | # Guess you wants 18 | * [Plugin Commands](goctl-plugin.md) 19 | * [API IDL](api-grammar.md) -------------------------------------------------------------------------------- /en/practise.md: -------------------------------------------------------------------------------- 1 | # User Practise 2 | > [!TIP] 3 | > 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) 4 | 5 | * [Persistent layer cache](redis-cache.md) 6 | * [Business layer cache](buiness-cache.md) 7 | * [Queue](go-queue.md) 8 | * [Middle Ground System](datacenter.md) 9 | * [Stream Handler](stream.md) 10 | * [Online Exchange](online-exchange.md) -------------------------------------------------------------------------------- /en/prepare-other.md: -------------------------------------------------------------------------------- 1 | # Other 2 | > [!TIP] 3 | > 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) 4 | 5 | Before, we have prepared the Go environment, Go Module configuration, Goctl, protoc&protoc-gen-go installation, these are the environments that developers must prepare during the development phase, and you can optionally install the next environment, 6 | Because these environments generally exist on the server (installation work, operation and maintenance will be completed for you), but in order to complete the follow-up **demonstration** process, I suggest you install it locally, because most of our demo environments will be Locally based. 7 | The following only gives the necessary preparatory work, and does not give a detailed introduction in the length of the document. 8 | 9 | ## Other environment 10 | * [etcd](https://etcd.io/docs/current/rfc/v3api/) 11 | * [redis](https://redis.io/) 12 | * [mysql](https://www.mysql.com/) -------------------------------------------------------------------------------- /en/prepare.md: -------------------------------------------------------------------------------- 1 | # Prepare 2 | > [!TIP] 3 | > 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) 4 | 5 | Before officially entering the actual development, we need to do some preparations, such as: installation of the Go environment, installation of tools used for grpc code generation, 6 | Installation of the necessary tool Goctl, Golang environment configuration, etc., this section will contain the following subsections: 7 | 8 | * [Golang Installation](golang-install.md) 9 | * [Go Module Configuration](gomod-config.md) 10 | * [Goctl Installation](goctl-install.md) 11 | * [protoc & protoc-gen-go Installation](protoc-install.md) 12 | * [More](prepare-other.md) -------------------------------------------------------------------------------- /en/project-dev.md: -------------------------------------------------------------------------------- 1 | # Project Development 2 | > [!TIP] 3 | > 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) 4 | 5 | In the previous chapters, we have introduced go-zero from the dimensions of some concepts, backgrounds, and quick start. Seeing this, I believe you already have some understanding of go-zero. 6 | From here, we will start to explain the entire process from environment preparation to service deployment. In order to ensure that everyone can thoroughly understand the go-zero development process, then prepare your patience and move on. 7 | In the chapters, the following subsections will be included: 8 | * [Prepare](prepare.md) 9 | * [Golang Installation](golang-install.md) 10 | * [Go Module Configuration](gomod-config.md) 11 | * [Goctl Installation](goctl-install.md) 12 | * [protoc & protoc-gen-go Installation](protoc-install.md) 13 | * [More](prepare-other.md) 14 | * [Development Rules](dev-specification.md) 15 | * [Naming Rules](naming-spec.md) 16 | * [Route Rules](route-naming-spec.md) 17 | * [Coding Rules](coding-spec.md) 18 | * [Development Flow](dev-flow.md) 19 | * [Configuration Introduction](config-introduction.md) 20 | * [API Configuration](api-config.md) 21 | * [RPC Configuration](rpc-config.md) 22 | * [Business Development](business-dev.md) 23 | * [Directory Structure](service-design.md) 24 | * [Model Generation](model-gen.md) 25 | * [API Coding](api-coding.md) 26 | * [Business Coding](business-coding.md) 27 | * [JWT](jwt.md) 28 | * [Middleware](middleware.md) 29 | * [RPC Implement & Call](rpc-call.md) 30 | * [Error Handling](error-handle.md) 31 | * [CI/CD](ci-cd.md) 32 | * [Service Deployment](service-deployment.md) 33 | * [Log Collection](log-collection.md) 34 | * [Trace](trace.md) 35 | * [Monitor](service-monitor.md) -------------------------------------------------------------------------------- /en/protoc-install.md: -------------------------------------------------------------------------------- 1 | # protoc & protoc-gen-go安装 2 | > [!TIP] 3 | > 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) 4 | 5 | ## Forward 6 | protoc is a tool written in C++, which can translate proto files into codes in the specified language. In the go-zero microservices, we use grpc to communicate between services, and the writing of grpc requires the use of protoc and the plug-in protoc-gen-go that translates into go language rpc stub code. 7 | 8 | Demonstration environment of this document 9 | * mac OS 10 | * protoc 3.14.0 11 | 12 | ## protoc installation 13 | 14 | * Enter the [protobuf release](https://github.com/protocolbuffers/protobuf/releases) page and select the compressed package file suitable for your operating system 15 | * Unzip `protoc-3.14.0-osx-x86_64.zip` and enter `protoc-3.14.0-osx-x86_64` 16 | ```shell 17 | $ cd protoc-3.14.0-osx-x86_64/bin 18 | ``` 19 | * Move the started `protoc` binary file to any path added to the environment variable, such as `$GOPATH/bin`. It is not recommended putting it directly with the next path of the system. 20 | ```shell 21 | $ mv protoc $GOPATH/bin 22 | ``` 23 | > [!TIP] 24 | > $GOPATH is the actual folder address of your local machine 25 | * Verify the installation result 26 | ```shell 27 | $ protoc --version 28 | ``` 29 | ```shell 30 | libprotoc 3.14.0 31 | ``` 32 | ## protoc-gen-* installation 33 | With goctl versions greater than 1.2.1, there is no need to install the `protoc-gen-go` plugin, because after that version, goctl has been implemented as a plugin for `protoc`, and goctl will automatically 34 | create a symbolic link `protoc-gen-goctl` to `goctl`, which will generate pb.go according to the following logic. 35 | 1. check if the `protoc-gen-goctl` plug-in exists in the environment variable, if so, skip to step 3 36 | 2. detect the existence of `protoc-gen-go` plugin in the environment variable, if not, the generation process is finished 37 | 3. generate pb.go based on the detected plugins 38 | 39 | > [!TIPS] 40 | > 41 | > Windows may report an error, `A required privilege is not held by the client.`, because goctl needs to be run `as administrator` under Windows. 42 | >The reason is that goctl needs to be run "as administrator" under Windows. 43 | * Download and install `protoc-gen-go` 44 | 45 | If the goctl version is already 1.2.1 or later, you can ignore this step. 46 | 47 | ```shell 48 | $ go get -u github.com/golang/protobuf/protoc-gen-go@v1.3.2 49 | ``` 50 | ```text 51 | go: found github.com/golang/protobuf/protoc-gen-go in github.com/golang/protobuf v1.4.3 52 | go: google.golang.org/protobuf upgrade => v1.25.0 53 | ``` 54 | * Move protoc-gen-go to any path where environment variables are added, such as `$GOPATH/bin`, because the binary itself after `go get` is in the `$GOPATH/bin` directory, so just make sure your `$GOPATH/bin` can be in the environment variable. 55 | 56 | > **[!WARNING] 57 | > protoc-gen-go installation failed, please read [Error](error.md) 58 | -------------------------------------------------------------------------------- /en/quick-start.md: -------------------------------------------------------------------------------- 1 | # Quick Start 2 | > [!TIP] 3 | > 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) 4 | 5 | This section mainly starts by quickly starting services such as api/rpc to let everyone have a macro concept of the project developed with go-zero, and we will introduce them in more detail in the follow-up. If you have already prepared the environment and tools with reference to [prepare](prepare.md), please follow the following sections to start the experience: 6 | 7 | * [monolithic service](monolithic-service.md) 8 | * [micro service](micro-service.md) 9 | -------------------------------------------------------------------------------- /en/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/3aefec98-56eb-45a6-a4b2-9adbdf4d63c0.png -------------------------------------------------------------------------------- /en/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/3bbddc1ebb79455da91dfcf3da6bc72f_tplv-k3u1fbpfcp-zoom-1.image.png -------------------------------------------------------------------------------- /en/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/76108cc071154e2faa66eada81857fb0_tplv-k3u1fbpfcp-zoom-1.image.png -------------------------------------------------------------------------------- /en/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/7715f4b6-8739-41ac-8c8c-04d187172e9d.png -------------------------------------------------------------------------------- /en/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/7e0fd2b8-d4c1-4130-a216-a7d3d4301116.png -------------------------------------------------------------------------------- /en/resource/alert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/alert.png -------------------------------------------------------------------------------- /en/resource/api-compare.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/api-compare.png -------------------------------------------------------------------------------- /en/resource/api-new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/api-new.png -------------------------------------------------------------------------------- /en/resource/author.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/author.jpeg -------------------------------------------------------------------------------- /en/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/b97bf7df-1781-436e-bf04-f1dd90c60537.png -------------------------------------------------------------------------------- /en/resource/book.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/book.zip -------------------------------------------------------------------------------- /en/resource/c42c34e8d33d48ec8a63e56feeae882a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/c42c34e8d33d48ec8a63e56feeae882a.png -------------------------------------------------------------------------------- /en/resource/ci-cd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/ci-cd.png -------------------------------------------------------------------------------- /en/resource/clone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/clone.png -------------------------------------------------------------------------------- /en/resource/compare.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/compare.png -------------------------------------------------------------------------------- /en/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/dc500acd526d40aabfe4f53cf5bd180a_tplv-k3u1fbpfcp-zoom-1.png -------------------------------------------------------------------------------- /en/resource/doc-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/doc-edit.png -------------------------------------------------------------------------------- /en/resource/docker_env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/docker_env.png -------------------------------------------------------------------------------- /en/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/f93c621571074e44a2d403aa25e7db6f_tplv-k3u1fbpfcp-zoom-1.png -------------------------------------------------------------------------------- /en/resource/fork.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/fork.png -------------------------------------------------------------------------------- /en/resource/fx_log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/fx_log.png -------------------------------------------------------------------------------- /en/resource/gitlab-git-url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/gitlab-git-url.png -------------------------------------------------------------------------------- /en/resource/go-zero-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/go-zero-logo.png -------------------------------------------------------------------------------- /en/resource/go-zero-practise.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/go-zero-practise.png -------------------------------------------------------------------------------- /en/resource/go_live_template.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/go_live_template.png -------------------------------------------------------------------------------- /en/resource/goctl-api-select.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/goctl-api-select.png -------------------------------------------------------------------------------- /en/resource/goctl-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/goctl-api.png -------------------------------------------------------------------------------- /en/resource/goctl-command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/goctl-command.png -------------------------------------------------------------------------------- /en/resource/grafana-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/grafana-app.png -------------------------------------------------------------------------------- /en/resource/grafana-panel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/grafana-panel.png -------------------------------------------------------------------------------- /en/resource/grafana-qps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/grafana-qps.png -------------------------------------------------------------------------------- /en/resource/grafana.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/grafana.png -------------------------------------------------------------------------------- /en/resource/handler.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/handler.gif -------------------------------------------------------------------------------- /en/resource/info.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/info.gif -------------------------------------------------------------------------------- /en/resource/intellij-model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/intellij-model.png -------------------------------------------------------------------------------- /en/resource/jenkins-add-credentials.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-add-credentials.png -------------------------------------------------------------------------------- /en/resource/jenkins-build-with-parameters.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-build-with-parameters.png -------------------------------------------------------------------------------- /en/resource/jenkins-choice.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-choice.png -------------------------------------------------------------------------------- /en/resource/jenkins-configure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-configure.png -------------------------------------------------------------------------------- /en/resource/jenkins-credentials-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-credentials-id.png -------------------------------------------------------------------------------- /en/resource/jenkins-credentials.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-credentials.png -------------------------------------------------------------------------------- /en/resource/jenkins-git.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-git.png -------------------------------------------------------------------------------- /en/resource/jenkins-new-item.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jenkins-new-item.png -------------------------------------------------------------------------------- /en/resource/json_tag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/json_tag.png -------------------------------------------------------------------------------- /en/resource/jump.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/jump.gif -------------------------------------------------------------------------------- /en/resource/k8s-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/k8s-01.png -------------------------------------------------------------------------------- /en/resource/k8s-02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/k8s-02.png -------------------------------------------------------------------------------- /en/resource/k8s-03.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/k8s-03.png -------------------------------------------------------------------------------- /en/resource/live_template.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/live_template.gif -------------------------------------------------------------------------------- /en/resource/log-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/log-flow.png -------------------------------------------------------------------------------- /en/resource/log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/log.png -------------------------------------------------------------------------------- /en/resource/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/logo.png -------------------------------------------------------------------------------- /en/resource/new_pr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/new_pr.png -------------------------------------------------------------------------------- /en/resource/pipeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/pipeline.png -------------------------------------------------------------------------------- /en/resource/pr_record.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/pr_record.png -------------------------------------------------------------------------------- /en/resource/project_generate_code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/project_generate_code.png -------------------------------------------------------------------------------- /en/resource/prometheus-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/prometheus-flow.png -------------------------------------------------------------------------------- /en/resource/prometheus-graph.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/prometheus-graph.webp -------------------------------------------------------------------------------- /en/resource/prometheus-start.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/prometheus-start.png -------------------------------------------------------------------------------- /en/resource/psiTree.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/psiTree.png -------------------------------------------------------------------------------- /en/resource/redis-cache-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-01.png -------------------------------------------------------------------------------- /en/resource/redis-cache-02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-02.png -------------------------------------------------------------------------------- /en/resource/redis-cache-03.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-03.png -------------------------------------------------------------------------------- /en/resource/redis-cache-04.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-04.png -------------------------------------------------------------------------------- /en/resource/redis-cache-05.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-05.png -------------------------------------------------------------------------------- /en/resource/redis-cache-06.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-06.png -------------------------------------------------------------------------------- /en/resource/redis-cache-07.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-07.png -------------------------------------------------------------------------------- /en/resource/redis-cache-08.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-08.png -------------------------------------------------------------------------------- /en/resource/redis-cache-09.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-09.webp -------------------------------------------------------------------------------- /en/resource/redis-cache-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-10.png -------------------------------------------------------------------------------- /en/resource/redis-cache-11.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/redis-cache-11.webp -------------------------------------------------------------------------------- /en/resource/service.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/service.gif -------------------------------------------------------------------------------- /en/resource/service.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/service.png -------------------------------------------------------------------------------- /en/resource/ssh-add-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/ssh-add-key.png -------------------------------------------------------------------------------- /en/resource/type.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/type.gif -------------------------------------------------------------------------------- /en/resource/user-pipeline-script.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeromicro/go-zero-doc/b1ddfe6dc62aac06f4bd7b7caa96cc7298d8f031/en/resource/user-pipeline-script.png -------------------------------------------------------------------------------- /en/route-naming-spec.md: -------------------------------------------------------------------------------- 1 | # Route Rules 2 | > [!TIP] 3 | > 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) 4 | 5 | * Recommended spine naming 6 | * Combinations of lowercase words and horizontal bars (-) 7 | * What you see is what you get 8 | 9 | ```go 10 | /user/get-info 11 | /user/get/info 12 | /user/password/change/:id 13 | ``` -------------------------------------------------------------------------------- /en/rpc-config.md: -------------------------------------------------------------------------------- 1 | # RPC Configuration 2 | > [!TIP] 3 | > 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) 4 | 5 | 6 | The rpc configuration controls various functions of an rpc service, including but not limited to listening address, etcd configuration, timeout, fuse configuration, etc. Below we will use a common rpc service configuration to illustrate. 7 | 8 | ## Configuration instructions 9 | ```go 10 | Config struct { 11 | zrpc.RpcServerConf 12 | CacheRedis cache.CacheConf // Redis cache configuration, see the api configuration instructions for details, and I won’t go into details here 13 | Mysql struct { // mysql database access configuration, see api configuration instructions for details, not repeat here 14 | DataSource string 15 | } 16 | } 17 | ``` 18 | 19 | ### zrpc.RpcServerConf 20 | ```go 21 | RpcServerConf struct { 22 | service.ServiceConf // mysql database access configuration, see api configuration instructions for details, not repeat here 23 | ListenOn string // rpc listening address and port, such as: 127.0.0.1:8888 24 | Etcd discov.EtcdConf `json:",optional"` // etcd related configuration 25 | Auth bool `json:",optional"` // Whether to enable Auth, if yes, Redis is required 26 | Redis redis.RedisKeyConf `json:",optional"` // Auth verification 27 | StrictControl bool `json:",optional"` // Whether it is Strict mode, if it is, the error is Auth failure, otherwise it can be considered as successful 28 | // pending forever is not allowed 29 | // never set it to 0, if zero, the underlying will set to 2s automatically 30 | Timeout int64 `json:",default=2000"` // Timeout control, unit: milliseconds 31 | CpuThreshold int64 `json:",default=900,range=[0:1000]"` // CPU load reduction threshold, the default is 900, the allowable setting range is 0 to 1000 32 | } 33 | ``` 34 | 35 | ### discov.EtcdConf 36 | ```go 37 | type EtcdConf struct { 38 | Hosts []string // etcd host array 39 | Key string // rpc registration key 40 | } 41 | ``` 42 | 43 | ### redis.RedisKeyConf 44 | ```go 45 | RedisConf struct { 46 | Host string // redis host 47 | Type string `json:",default=node,options=node|cluster"` // redis type 48 | Pass string `json:",optional"` // redis password 49 | } 50 | 51 | RedisKeyConf struct { 52 | RedisConf 53 | Key string `json:",optional"` // Verification key 54 | } 55 | ``` 56 | -------------------------------------------------------------------------------- /en/rpc-dir.md: -------------------------------------------------------------------------------- 1 | # RPC Directory Structure 2 | > [!TIP] 3 | > 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) 4 | 5 | ```text 6 | . 7 | ├── etc // yaml configuration file 8 | │ └── greet.yaml 9 | ├── go.mod 10 | ├── greet // pb.go folder① 11 | │ └── greet.pb.go 12 | ├── greet.go // main entry 13 | ├── greet.proto // proto source file 14 | ├── greetclient // call logic ② 15 | │ └── greet.go 16 | └── internal 17 | ├── config // yaml configuration corresponding entity 18 | │ └── config.go 19 | ├── logic // Business code 20 | │ └── pinglogic.go 21 | ├── server // rpc server 22 | │ └── greetserver.go 23 | └── svc // Dependent resources 24 | └── servicecontext.go 25 | ``` 26 | 27 | > [!TIP] 28 | > ① The name of the pb folder (the old version folder is fixed as pb) is taken from the value of option go_package in the proto file. The last level is converted according to a certain format. If there is no such declaration, it is taken from the value of package. The approximate code is as follows: 29 | 30 | ```go 31 | if option.Name == "go_package" { 32 | ret.GoPackage = option.Constant.Source 33 | } 34 | ... 35 | if len(ret.GoPackage) == 0 { 36 | ret.GoPackage = ret.Package.Name 37 | } 38 | ret.PbPackage = GoSanitized(filepath.Base(ret.GoPackage)) 39 | ... 40 | ``` 41 | > [!TIP] 42 | > For GoSanitized method, please refer to google.golang.org/protobuf@v1.25.0/internal/strs/strings.go:71 43 | 44 | > [!TIP] 45 | > ② The name of the call layer folder is taken from the name of the service in the proto. If the name of the sercice is equal to the name of the pb folder, the client will be added after service to distinguish between pb and call. 46 | 47 | ```go 48 | if strings.ToLower(proto.Service.Name) == strings.ToLower(proto.GoPackage) { 49 | callDir = filepath.Join(ctx.WorkDir, strings.ToLower(stringx.From(proto.Service.Name+"_client").ToCamel())) 50 | } 51 | ``` -------------------------------------------------------------------------------- /en/service-design.md: -------------------------------------------------------------------------------- 1 | # Directory Structure 2 | > [!TIP] 3 | > 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) 4 | 5 | Directory splitting refers to the directory splitting in line with the best practices of go-zero, which is related to the splitting of microservices. In the best practice within the team, 6 | We split a system into multiple subsystems according to the horizontal division of the business, and each subsystem should have an independent persistent storage and cache system. 7 | For example, a shopping mall system needs to consist of a user system (user), a product management system (product), an order system (order), a shopping cart system (cart), a settlement center system (pay), an after-sale system (afterSale), etc. 8 | 9 | ## System structure analysis 10 | In the mall system mentioned above, while each system provides services to the outside (http), it also provides data to other subsystems for data access interfaces (rpc), so each subsystem can be split into a service , And provides two external ways to access the system, api and rpc, therefore, 11 | The above system is divided into the following structure according to the directory structure: 12 | 13 | ```text 14 | . 15 | ├── afterSale 16 | │   ├── api 17 | │   └── rpc 18 | ├── cart 19 | │   ├── api 20 | │   └── rpc 21 | ├── order 22 | │   ├── api 23 | │   └── rpc 24 | ├── pay 25 | │   ├── api 26 | │   └── rpc 27 | ├── product 28 | │   ├── api 29 | │   └── rpc 30 | └── user 31 | ├── api 32 | └── rpc 33 | ``` 34 | 35 | ## rpc call chain suggestion 36 | When designing the system, try to make the call between services one-way in the chain instead of cyclically. For example, the order service calls the user service, and the user service does not call the order service in turn. 37 | When one of the services fails to start, it will affect each other and enter an infinite loop. You order to think it is caused by the user service failure, and the user thinks it is caused by the order service. If there are a large number of services in a mutual call chain, 38 | You need to consider whether the service split is reasonable. 39 | 40 | ## Directory structure of common service types 41 | Among the above services, only api/rpc services are listed. In addition, there may be more service types under one service, such as rmq (message processing system), cron (timed task system), script (script), etc. , 42 | Therefore, a service may contain the following directory structure: 43 | 44 | ```text 45 | user 46 | ├── api // http access service, business requirement realization 47 | ├── cronjob // Timed task, timed data update service 48 | ├── rmq // Message processing system: mq and dq, handle some high concurrency and delay message services 49 | ├── rpc // rpc service to provide basic data access to other subsystems 50 | └── script // Script, handle some temporary operation requirements, and repair temporary data 51 | ``` 52 | 53 | ## Example of complete project directory structure 54 | ```text 55 | mall // 工程名称 56 | ├── common // 通用库 57 | │   ├── randx 58 | │   └── stringx 59 | ├── go.mod 60 | ├── go.sum 61 | └── service // 服务存放目录 62 | ├── afterSale 63 | │   ├── api 64 | │   └── model 65 | │   └── rpc 66 | ├── cart 67 | │   ├── api 68 | │   └── model 69 | │   └── rpc 70 | ├── order 71 | │   ├── api 72 | │   └── model 73 | │   └── rpc 74 | ├── pay 75 | │   ├── api 76 | │   └── model 77 | │   └── rpc 78 | ├── product 79 | │   ├── api 80 | │   └── model 81 | │   └── rpc 82 | └── user 83 | ├── api 84 | ├── cronjob 85 | ├── model 86 | ├── rmq 87 | ├── rpc 88 | └── script 89 | ``` 90 | 91 | # Guess you wants 92 | * [API Directory Structure](api-dir.md) 93 | -------------------------------------------------------------------------------- /en/source.md: -------------------------------------------------------------------------------- 1 | # Source Code 2 | > [!TIP] 3 | > 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) 4 | 5 | * [demo](https://github.com/zeromicro/go-zero-demo) -------------------------------------------------------------------------------- /en/summary.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | * [Introduction](README.md) 4 | * [About Us](about-us.md) 5 | * [Join Us](join-us.md) 6 | * [Concepts](concept-introduction.md) 7 | * [Quick Start](quick-start.md) 8 | * [Monolithic Service](monolithic-service.md) 9 | * [Micro Service](micro-service.md) 10 | * [Framework Design](framework-design.md) 11 | * [Go-Zero Design](go-zero-design.md) 12 | * [Go-Zero Features](go-zero-features.md) 13 | * [API IDL](api-grammar.md) 14 | * [API Directory Structure](api-dir.md) 15 | * [RPC Directory Structure](rpc-dir.md) 16 | * [Project Development](project-dev.md) 17 | * [Prepare](prepare.md) 18 | * [Golang Installation](golang-install.md) 19 | * [Go Module Configuration](gomod-config.md) 20 | * [Goctl Installation](goctl-install.md) 21 | * [protoc & protoc-gen-go Installation](protoc-install.md) 22 | * [More](prepare-other.md) 23 | * [Development Rules](dev-specification.md) 24 | * [Naming Rules](naming-spec.md) 25 | * [Route Rules](route-naming-spec.md) 26 | * [Coding Rules](coding-spec.md) 27 | * [Development Flow](dev-flow.md) 28 | * [Configuration Introduction](config-introduction.md) 29 | * [API Configuration](api-config.md) 30 | * [RPC Configuration](rpc-config.md) 31 | * [Business Development](business-dev.md) 32 | * [Directory Structure](service-design.md) 33 | * [Model Generation](model-gen.md) 34 | * [API Coding](api-coding.md) 35 | * [Business Coding](business-coding.md) 36 | * [JWT](jwt.md) 37 | * [Middleware](middleware.md) 38 | * [RPC Implement & Call](rpc-call.md) 39 | * [Error Handling](error-handle.md) 40 | * [CI/CD](ci-cd.md) 41 | * [Service Deployment](service-deployment.md) 42 | * [Log Collection](log-collection.md) 43 | * [Trace](trace.md) 44 | * [Monitor](service-monitor.md) 45 | * [Goctl](goctl.md) 46 | * [Commands & Flags](goctl-commands.md) 47 | * [API Commands](goctl-api.md) 48 | * [RPC Commands](goctl-rpc.md) 49 | * [Model Commands](goctl-model.md) 50 | * [Plugin Commands](goctl-plugin.md) 51 | * [More Commands](goctl-other.md) 52 | * [Template](template-manage.md) 53 | * [Command](template-cmd.md) 54 | * [Custom](template.md) 55 | * [Components](component-center.md) 56 | * [logx](logx.md) 57 | * [bloom](bloom.md) 58 | * [executors](executors.md) 59 | * [fx](fx.md) 60 | * [mysql](mysql.md) 61 | * [redis-lock](redis-lock.md) 62 | * [periodlimit](periodlimit.md) 63 | * [tokenlimit](tokenlimit.md) 64 | * [TimingWheel](timing-wheel.md) 65 | * [Tools](tool-center.md) 66 | * [Intellij Plugin](intellij.md) 67 | * [VSCode Plugin](vscode.md) 68 | * [Plugins](plugin-center.md) 69 | * [Learning Resources](learning-resource.md) 70 | * [Wechat](wechat.md) 71 | * [Night](goreading.md) 72 | * [OpenTalk](gotalk.md) 73 | * [User Practise](practise.md) 74 | * [Persistent layer cache](redis-cache.md) 75 | * [Business layer cache](buiness-cache.md) 76 | * [Queue](go-queue.md) 77 | * [Middle Ground System](datacenter.md) 78 | * [Stream Handler](stream.md) 79 | * [Online Exchange](online-exchange.md) 80 | * [Contributor](contributor.md) 81 | * [Document Contribute](doc-contibute.md) 82 | * [Error](error.md) 83 | * [Source Code](source.md) 84 | 85 | -------------------------------------------------------------------------------- /en/template-manage.md: -------------------------------------------------------------------------------- 1 | # Template 2 | 3 | - [Command](template-cmd.md) 4 | - [Custom](template.md) -------------------------------------------------------------------------------- /en/tool-center.md: -------------------------------------------------------------------------------- 1 | # Tools 2 | > [!TIP] 3 | > 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) 4 | 5 | In go-zero, a lot of tools to improve engineering efficiency are provided, such as api and rpc generation. On this basis, the compilation of api files seems so weak. 6 | Because of the lack of highlighting, code hints, template generation, etc., this section will show you how go-zero solves these problems. This section contains the following subsections: 7 | * [Intellij plugin](intellij.md) 8 | * [VSCode plugin](vscode.md) -------------------------------------------------------------------------------- /en/vscode.md: -------------------------------------------------------------------------------- 1 | # vs code plugin 2 | > [!TIP] 3 | > 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) 4 | 5 | The plug-in can be installed on the 1.46.0+ version of Visual Studio Code. First, please make sure that your Visual Studio Code version meets the requirements and the goctl command line tool has been installed. If Visual Studio Code is not installed, please install and open Visual Studio Code. Navigate to the "Extensions" pane, search for goctl and install this extension (publisher ID is "xiaoxin-technology.goctl"). 6 | 7 | For the extension of Visual Studio Code, please refer to [here](https://code.visualstudio.com/docs/editor/extension-gallery). 8 | 9 | ## Features 10 | 11 | * Syntax highlighting 12 | * Jump to definition/reference 13 | * Code formatting 14 | * Code block hint 15 | 16 | ### Syntax highlighting 17 | 18 | ### Jump to definition/reference 19 | 20 | ![jump](./resource/jump.gif) 21 | 22 | ### Code formatting 23 | 24 | Invoke the goctl command line formatting tool, please make sure that goctl has been added to `$PATH` and has executable permissions before use 25 | 26 | ### Code block hint 27 | 28 | #### info block 29 | 30 | ![info](./resource/info.gif) 31 | 32 | #### type block 33 | 34 | ![type](./resource/type.gif) 35 | 36 | #### service block 37 | 38 | ![type](./resource/service.gif) 39 | 40 | #### handler block 41 | 42 | ![type](./resource/handler.gif) 43 | -------------------------------------------------------------------------------- /en/wechat.md: -------------------------------------------------------------------------------- 1 | # Wechat 2 | > [!TIP] 3 | > 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) 4 | 5 | 6 | Microservices actual combat is the official official account of go-zero, where the latest go-zero best practices will be released, synchronized go night reading, go open source, GopherChina, Tencent Cloud Developer Conference and other channels about the latest go-zero Technology and information. 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |
NameAuthorQrCode
微服务实战kevwan微服务实践
20 | 21 | # Articles(Simplified Chinese) 22 | Here are some articles. If you want to get more go-zero best practice dry goods, you can follow the public account for the latest developments. 23 | * [《一文读懂云原生 go-zero 微服务框架》](https://mp.weixin.qq.com/s/gszj3-fwfcof5Tt2Th4dFA) 24 | * [《你还在手撕微服务？快试试 go-zero 的微服务自动生成》](https://mp.weixin.qq.com/s/Qvi-g3obgD_FVJ7CK3O56w) 25 | * [《最简单的Go Dockerfile编写姿势，没有之一！》](https://mp.weixin.qq.com/s/VLBiIbZStKhb7uth1ndgQQ) 26 | * [《通过MapReduce降低服务响应时间》](https://mp.weixin.qq.com/s/yxXAIK1eC_X22DH4ssZSag) 27 | * [《微服务过载保护原理与实战](https://mp.weixin.qq.com/s/CWzf6CY2R12Xd-rIYVvdPQ) 28 | * [《最简单的 K8S 部署文件编写姿势，没有之一！》](https://mp.weixin.qq.com/s/1GOMxlI8ocOL3U_I2TKPzQ) 29 | * [《go-zero 如何应对海量定时/延迟任务？》](https://mp.weixin.qq.com/s/CiZ5SpuT-VN8V9wil8_iGg) 30 | * [《go-zero 如何扛住流量冲击（一）》](https://mp.weixin.qq.com/s/xnJIm3asMncBfbtXo22sZw) 31 | * [《服务自适应降载保护设计》](https://mp.weixin.qq.com/s/cgjCL59e3CDWhsxzwkuKBg) -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED 2 | 本项目已迁移指 https://github.com/zeromicro/zero-doc/tree/main/go-zero.dev 3 | 4 | pr 见 https://github.com/zeromicro/zero-doc/pull/62 --------------------------------------------------------------------------------