Skip to content

Commit cd95d11

Browse files
jaronniejaronnie
committed
feat(docs): enhance proto/serverless/template (#398)
feat(docs): enhance proto/serverless/template
1 parent c42d4a8 commit cd95d11

3 files changed

Lines changed: 224 additions & 43 deletions

File tree

‎docs/src/guide/proto.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,13 @@ star: true
55
order: 1
66
---
77

8-
:::tip jzero 支持多 proto 进行管理 proto(goctl 原生工具不支持).
8+
## 特性
99

10-
jzero 在自动生成代码的时候会自动识别 desc/proto 下的文件并自动注册到 zrpc 上.
11-
jzero 默认支持对 proto 的字段校验
12-
:::
13-
14-
jzero 框架的理念是:
15-
16-
* 不同模块分在不同的 proto 文件下
17-
18-
jzero 中 proto 规范:
19-
20-
* proto 文件引用规范: 依据于 go-zero 的 proto 规范， 即 service 的 rpc 方法中入参和出参的 proto 不能是 import 的 proto 文件中的 message, 只能在当前文件
10+
- ✅ **支持多 proto 文件**：可在项目中定义多个 proto 文件（如 user.proto、order.proto、product.proto）
11+
- ✅ 支持**引入公共 proto** 文件
12+
- ✅ **一键生成 RPC 客户端**：生成独立的 RPC 客户端代码，脱离服务端依赖，解耦服务端和客户端
13+
- ✅ **内置字段验证**：基于 `buf.validate` 实现自动参数校验
14+
- ✅ **灵活中间件配置**：支持为整个 service 或单个 method 配置 HTTP/RPC 中间件
2115

2216
## proto 文件示例
2317

@@ -62,7 +56,15 @@ import "buf/validate/validate.proto";
6256
6357
option go_package = "./pb/versionpb";
6458
65-
message VersionRequest {
59+
// 使用内置规则
60+
message CreateRequest {
61+
string email = 1 [(buf.validate.field).string.email = true];
62+
int32 age = 2 [(buf.validate.field).int32.gt = 17];
63+
string name = 3 [(buf.validate.field).string.min_len = 2];
64+
}
65+
66+
// cel 表达式, 支持自定义 message
67+
message GetRequest {
6668
int32 id = 1 [
6769
(buf.validate.field).cel = {
6870
id: "id.length"
@@ -73,6 +75,8 @@ message VersionRequest {
7375
}
7476
```
7577

78+
**内置规则如果有国际化需求, 可使用 [protovalidate-translator](https://github.com/jzero-io/protovalidate-translator)**
79+
7680
## middleware
7781

7882
添加 middleware, 多个 middleware 使用逗号隔开

‎docs/src/guide/serverless.md‎

Lines changed: 123 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,44 +5,144 @@ star: true
55
order: 5.4
66
---
77

8-
jzero 支持插件化机制, 可以方便的进行插件的安装和卸载操作.
8+
jzero 支持插件化机制, 可以方便的进行插件的安装和卸载操作.
99

10-
## 新增插件
10+
核心点在于**多模块协同开发**, 最终编译成**单体服务部署**.
1111

12-
```shell
13-
# api 项目插件
14-
jzero new your_plugin --frame api --serverless
15-
# api 项目插件 mono
16-
jzero new your_plugin --frame api --serverless --mono
17-
18-
# rpc 项目插件
19-
jzero new your_plugin --frame rpc --serverless
20-
# rpc 项目插件 mono
21-
jzero new your_plugin --frame rpc --serverless --mono
22-
23-
# gateway 项目插件
24-
jzero new your_plugin --frame gateway --serverless
25-
# gateway 项目插件 mono
26-
jzero new your_plugin --frame gateway --serverless --mono
27-
```
12+
## 新增插件(以 api 项目为例)
2813

29-
## 编译项目
30-
31-
```shell
14+
```bash
15+
# 新增 api 项目
16+
jzero new simpleapi
17+
# 进入项目目录
18+
cd simpleapi
19+
# 新增 api 项目插件(独立 go module)
20+
jzero new your_plugin --frame api --serverless
21+
# 新增 api 项目插件(与主服务 simpleapi 共用 go module )
22+
jzero new your_mono_plugin --frame api --serverless --mono
23+
# 执行 serverless build, 主服务接管插件路由(plugins/plugins.go)
3224
jzero serverless build
33-
25+
# 下载依赖
26+
go mod tidy
27+
# 大单体编译产物
3428
go build
3529
```
3630

3731
## 卸载插件
3832

3933
```shell
40-
# 卸载所有
34+
# 卸载所有, 主服务不再接管插件路由
4135
jzero serverless delete
4236

4337
# 卸载指定插件
4438
jzero serverless delete --plugin <plugin-name>
4539

4640
# 重新编译
4741
go build
42+
```
43+
44+
## 项目结构
45+
46+
```bash
47+
simpleapi
48+
├── Dockerfile
49+
├── README.md
50+
├── cmd
51+
│   ├── root.go
52+
│   ├── server.go
53+
│   └── version.go
54+
├── desc
55+
│   ├── api
56+
│   │   └── version.api
57+
│   └── swagger
58+
│   ├── swagger.json
59+
│   └── version.swagger.json
60+
├── etc
61+
│   └── etc.yaml
62+
├── go.mod
63+
├── go.sum
64+
├── go.work
65+
├── go.work.sum
66+
├── internal
67+
│   ├── config
68+
│   │   └── config.go
69+
│   ├── custom
70+
│   │   └── custom.go
71+
│   ├── handler
72+
│   │   ├── routes.go
73+
│   │   └── version
74+
│   │   └── version.go
75+
│   ├── logic
76+
│   │   └── version
77+
│   │   └── version.go
78+
│   ├── middleware
79+
│   │   ├── middleware.go
80+
│   │   ├── response.go
81+
│   │   └── validator.go
82+
│   ├── svc
83+
│   │   ├── config.go
84+
│   │   ├── middleware.go
85+
│   │   └── servicecontext.go
86+
│   └── types
87+
│   ├── types.go
88+
│   └── version
89+
│   └── types.go
90+
├── main.go
91+
└── plugins
92+
├── plugins.go
93+
├── your_mono_plugin
94+
│   ├── Dockerfile
95+
│   ├── README.md
96+
│   ├── cmd
97+
│   │   ├── root.go
98+
│   │   ├── server.go
99+
│   │   └── version.go
100+
│   ├── etc
101+
│   │   └── etc.yaml
102+
│   ├── internal
103+
│   │   ├── config
104+
│   │   │   └── config.go
105+
│   │   ├── custom
106+
│   │   │   └── custom.go
107+
│   │   ├── handler
108+
│   │   │   └── routes.go
109+
│   │   ├── middleware
110+
│   │   │   ├── middleware.go
111+
│   │   │   ├── response.go
112+
│   │   │   └── validator.go
113+
│   │   └── svc
114+
│   │   ├── config.go
115+
│   │   ├── middleware.go
116+
│   │   └── servicecontext.go
117+
│   ├── main.go
118+
│   └── serverless
119+
│   └── serverless.go
120+
└── your_plugin
121+
├── Dockerfile
122+
├── README.md
123+
├── cmd
124+
│   ├── root.go
125+
│   ├── server.go
126+
│   └── version.go
127+
├── etc
128+
│   └── etc.yaml
129+
├── go.mod
130+
├── internal
131+
│   ├── config
132+
│   │   └── config.go
133+
│   ├── custom
134+
│   │   └── custom.go
135+
│   ├── handler
136+
│   │   └── routes.go
137+
│   ├── middleware
138+
│   │   ├── middleware.go
139+
│   │   ├── response.go
140+
│   │   └── validator.go
141+
│   └── svc
142+
│   ├── config.go
143+
│   ├── middleware.go
144+
│   └── servicecontext.go
145+
├── main.go
146+
└── serverless
147+
└── serverless.go
48148
```

‎docs/src/guide/template.md‎

Lines changed: 84 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,6 @@ jzero template init --branch gateway
2121
goctl template init --home .template/go-zero
2222
```
2323

24-
## 构建属于自己的模版
25-
26-
```shell
27-
# 将当前项目构建为模版，并保存到 $HOME/.jzero/templates/local 下
28-
jzero template build --name template_name
29-
```
30-
3124
## 使用自定义模版初始化项目
3225

3326
* 指定远程仓库模板
@@ -48,4 +41,88 @@ jzero new project_name --local template_name
4841

4942
```shell
5043
jzero new project_name --home path_to_template
44+
```
45+
46+
## 实战: 构建属于自己的模版
47+
48+
:::tip 可以将当前任意项目转换成 jzero 模板, 这非常 cool!
49+
:::
50+
51+
```bash
52+
# 新增一个 api 项目
53+
jzero new simpleapi
54+
# 进入项目
55+
cd simpleapi
56+
# 新增一个 api
57+
jzero add api helloworld
58+
# 生成代码
59+
jzero gen
60+
61+
# 将当前项目构建为模版, 并保存到 $HOME/.jzero/templates/local/myapi 下
62+
jzero template build --name myapi
63+
64+
# 此时就可以使用你自己构建的模板了, 你会发现生成的项目自动拥有了 helloworld api 了.
65+
jzero new mysimpleapi --local myapi
66+
67+
# 但是你发现该模板仅允许本地使用, 为了达到通用的效果
68+
# 你可以在远程仓库如 github 创建一个 templates 仓库(假设为 https://github.com/jzero-io/templates)
69+
# 然后将 $HOME/.jzero/templates/local/myapi 下的内容放到仓库中, 并上传到 myapi 分支
70+
jzero new project_name --remote https://github.com/jzero-io/templates --branch myapi
71+
```
72+
73+
模板结构如下:
74+
75+
```bash
76+
$ tree ~/.jzero/templates/local/myapi
77+
└── app
78+
├── Dockerfile.tpl
79+
├── README.md.tpl
80+
├── cmd
81+
│   ├── root.go.tpl
82+
│   ├── server.go.tpl
83+
│   └── version.go.tpl
84+
├── desc
85+
│   ├── api
86+
│   │   ├── helloworld.api.tpl
87+
│   │   └── version.api.tpl
88+
│   └── swagger
89+
│   ├── helloworld.swagger.json.tpl
90+
│   ├── swagger.json.tpl
91+
│   └── version.swagger.json.tpl
92+
├── etc
93+
│   └── etc.yaml.tpl
94+
├── go.mod.tpl
95+
├── internal
96+
│   ├── config
97+
│   │   └── config.go.tpl
98+
│   ├── custom
99+
│   │   └── custom.go.tpl
100+
│   ├── handler
101+
│   │   ├── helloworld
102+
│   │   │   └── helloworld_compact.go.tpl
103+
│   │   ├── routes.go.tpl
104+
│   │   └── version
105+
│   │   └── version.go.tpl
106+
│   ├── logic
107+
│   │   ├── helloworld
108+
│   │   │   └── create.go.tpl
109+
│   │   └── version
110+
│   │   └── version.go.tpl
111+
│   ├── middleware
112+
│   │   ├── middleware.go.tpl
113+
│   │   ├── response.go.tpl
114+
│   │   └── validator.go.tpl
115+
│   ├── svc
116+
│   │   ├── config.go.tpl
117+
│   │   ├── middleware.go.tpl
118+
│   │   └── servicecontext.go.tpl
119+
│   └── types
120+
│   ├── helloworld
121+
│   │   └── types.go.tpl
122+
│   ├── types.go.tpl
123+
│   └── version
124+
│   └── types.go.tpl
125+
├── main.go.tpl
126+
└── plugins
127+
└── plugins.go.tpl
51128
```

0 commit comments

Comments
 (0)