1.7 KiB
1.7 KiB
质量与命名规范
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 里兼容多形态的联合类型(如
RespInputstring|数组)必须成对实现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(去空白),字段顺序与内容保持原样,符合保真要求。