34 lines
2.1 KiB
Markdown
34 lines
2.1 KiB
Markdown
# 质量与命名规范
|
|
|
|
> Go 后端工具链检查与命名约定。
|
|
|
|
## 工具链(提交前必过)
|
|
|
|
- 提交前必须通过 `gofmt`/`goimports`、`go vet ./...`、`go test ./...`。
|
|
- 仓库有 `golangci-lint` 配置时以其为准。
|
|
- 依赖变更后运行 `go mod tidy`,`go.mod` 与 `go.sum` 一起提交。
|
|
|
|
## 命名
|
|
|
|
- 一律 MixedCaps,不用下划线;缩写词大小写保持一致:`ociConfigID`、`ParseURL`、`HTTPClient`。
|
|
- 包名小写单个词,不用 `util`、`common`、`base` 这类空泛名。
|
|
- 变量名长度与作用域成正比:循环变量可用 `i`、`c`,包级变量用完整单词。
|
|
- Getter 不加 `Get` 前缀:`user.Name()` 而非 `user.GetName()`。
|
|
- 方法接收者 1~2 个字母且同一类型内保持一致,如 `func (s *InstanceService)`。
|
|
- 错误变量:导出 sentinel 用 `ErrXxx`,包内用 `errXxx`;自定义错误类型以 `Error` 结尾。
|
|
|
|
## JSON 联合类型与内容留档保真(2026-07 内容日志失真教训)
|
|
|
|
- aiwire 里兼容多形态的联合类型(如 `RespInput` string|数组)**必须成对实现**
|
|
`UnmarshalJSON` 与 `MarshalJSON`:只写 Unmarshal 时,任何再序列化(内容日志、
|
|
测试快照)都会退化成 Go 字段名形态(`{"Text":"","Items":[...],"IsArray":true}`),
|
|
排障者复制它复现会直接 400。参考 `aiwire/openai.go Content` 的保形写法,
|
|
往返用 table-driven 测试锁定(`aiwire/responses_test.go`)。
|
|
- 留档「客户端请求正文」优先存**原始字节**(`json.RawMessage(raw)`),不要存解析
|
|
后的结构体:直通端点未建模字段会被结构体序列化悄悄丢掉。`json.Marshal` 对
|
|
RawMessage 会 compact(去空白),字段顺序与内容保持原样,符合保真要求。
|
|
|
|
## 多字段设置接口用字段级 PATCH,不用全量 PUT
|
|
|
|
「改一存一」交互的设置面板(安全设置、OAuth provider 等)服务端用字段级 PATCH:DTO 全指针字段,nil=沿用现值,只落库出现的字段(合并到现值后整体校验);全量 PUT 下并发编辑各自基于旧快照,后到请求会回滚他人字段、复活已清空配置(2026-07-22 审查 #18,security.go `SecurityPatch` / oauthconfig.go `UpdateOAuthInput`)。
|