124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
## API
|
||
|
||
### goctl代码生成
|
||
|
||
可以在doc/genCode.md查看
|
||
|
||
```powershell
|
||
# 生成多个types类型的话需要关闭这个实验性功能
|
||
goctl env -w GOCTL_EXPERIMENTAL=off
|
||
|
||
# 代码生成，会自动处理引入的子api文件
|
||
goctl api go -api background.api -dir . --home D:/zhangyuxin/template/1.8.3
|
||
goctl api go -api login.api -dir . --home ../../../deploy/goctl
|
||
goctl api go -api main.api -dir . --home ../../deploy/goctl
|
||
```
|
||
|
||
### 参数校验
|
||
|
||
| 接收规则 | 说明 | 示例 |
|
||
| -------- | ------------------------------------------ | ------------------------------- |
|
||
| optional | 当前字段是可选参数，允许为零值(zero value) | `json:"foo,optional"` |
|
||
| options | 当前参数仅可接收的枚举值 | `json:"gender,options=foo|bar"` |
|
||
| default | 当前参数默认值 | `json:"gender,default=male"` |
|
||
| range | 当前参数数值有效范围，支持开/闭区间 | `json:"age,range=[0:120]"` |
|
||
|
||
#### **`optional`** **与** **`omitempty`** **的区别**
|
||
|
||
两者都写在 json/form tag 的 options 里，但作用域完全不同，不可互相替代
|
||
|
||
##### `optional` —— goctl 专用，控制 Swagger 与请求校验
|
||
|
||
- **Swagger 生成**：标了 `optional` 的字段不进 `required` 数组，Apifox/Swagger UI 显示为可选；未标的字段进 `required` 数组，显示为必填
|
||
- **请求校验**：goctl 生成的 logic 不会对标了 `optional` 的字段做必填校验
|
||
- **判定逻辑**：goctl 遍历 tag options，找到 `optional` 关键字即判定为可选
|
||
|
||
##### `omitempty` —— Go 标准库指令，控制 JSON 序列化
|
||
|
||
- **JSON 序列化**：字段为零值（0、""、nil、false）时，响应 JSON 中**不输出**该字段
|
||
- **Swagger 生成**：**goctl 完全不识别**，字段仍按未标 `optional` 处理，即判定为 required
|
||
- **请求校验**：无影响
|
||
|
||
## RPC
|
||
|
||
### goctl代码生成
|
||
|
||
```powershell
|
||
# 主proto文件代码生成
|
||
goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=. --proto_path=. -m --home ../../../deploy/goctl
|
||
|
||
# 主proto文件中引入的proto代码生成
|
||
protoc.exe -I ./ --go_out=. --go-grpc_out=. ./user_model.proto
|
||
|
||
```
|
||
|
||
当`proto`文件里面定义了多个 service的时候，需要额外注意，还要再main函数中手动注册一下
|
||
|
||
> 每个 proto 文件应该聚焦于一个核心概念/实体。一个文件里定义太多 service 通常是设计需要重新考虑的信号
|
||
|
||
注册示例
|
||
|
||
```go
|
||
import (
|
||
ebookServer "olive/services/product/rpc/internal/server/ebookservice"
|
||
)
|
||
|
||
var configFile = flag.String("f", "etc/product.yaml", "the config file")
|
||
|
||
func main() {
|
||
flag.Parse()
|
||
|
||
var c config.Config
|
||
conf.MustLoad(*configFile, &c)
|
||
ctx := svc.NewServiceContext(c)
|
||
|
||
s := zrpc.MustNewServer(c.RpcServerConf, func(grpcServer *grpc.Server) {
|
||
// 新服务
|
||
productrpcmodel.RegisterEbookServiceServer(grpcServer, ebookServer.NewEbookServiceServer(ctx))
|
||
})
|
||
defer s.Stop()
|
||
|
||
fmt.Printf("Starting product RPC server at %s...\n", c.ListenOn)
|
||
s.Start()
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### proto代码生成错误：File not found错误
|
||
|
||
- 错误描述
|
||
|
||
执行 protoc 报 google/protobuf/timestamp.proto: File not found. 的错提示File not found
|
||
|
||
- 解决方式
|
||
|
||
重新下载[protoc](https://github.com/protocolbuffers/protobuf/releases)，解压后，将整个include目录复制到protoc执行文件同一级目录下
|
||
|
||
|
||
|
||
|
||
|
||
## model
|
||
|
||
可以在doc/genCode.md查看
|
||
|
||
**Model 层**：只做 **“业务循环”** + **“SQL 查询”** + **“结果封装”**，不关心字符串到时间的转换和 Protobuf 类型。
|
||
|
||
### goctl代码生成
|
||
|
||
```powershell
|
||
# mysql根据远程数据库表生成
|
||
goctl model mysql datasource --url="olive:xxvkikaDDx01&&99@tcp(127.0.0.1:3306)/ebming" --table="user_invitation_record" --dir="." -c --home ../../../../deploy/goctl/1.8.3
|
||
|
||
# mysql根据ddl生成
|
||
goctl model mysql ddl --src h5.sql --dir . -c --home D:/zhangyuxin/template/1.8.3
|
||
|
||
# pgsql根据远程数据库表生成
|
||
goctl model pg datasource -url "postgres://labman:tN5bWz2KpL9Fy4@127.0.0.1:15432/sern" -table user -dir ./user --cache --home ../../goctl_template/1.8.3
|
||
|
||
# pgsql根据远程数据库表生成,带模式（schema）
|
||
goctl model pg datasource -url "postgres://admin:zhangyuxin@127.0.0.1:25432/test?sslmode=disable" -s "users" -table "profile" -dir ./go-zero/model/users/ --cache --home ../../deploy/goctl
|
||
```
|
||
|