# 质量与命名规范

> 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(去空白),字段顺序与内容保持原样,符合保真要求。