mirror of
https://github.com/wweir/sower.git
synced 2026-10-21 10:19:43 +00:00
56 lines
2.3 KiB
Markdown
56 lines
2.3 KiB
Markdown
## Coding Agent 规范
|
|
|
|
1. 优先使用 lsp 等工具，查询代码中的函数文档、结构、报错、调用
|
|
2. 对于描述上有模糊问题，需反复确认，直至补全所有需要的信息
|
|
3. 禁止重构代码实现，除非经过用户明确确认、授权
|
|
4. 遵循最小化修改面原则，以最小的修改面解决用户的问题
|
|
5. 入口函数在上，依赖的函数、方法按调用关系排列在下方
|
|
|
|
## 代码结构
|
|
|
|
使用 Go 语言开发，遵循 Go 项目标准目录结构
|
|
|
|
├── api # proto 文件、OpenAPI 文档等
|
|
├── cmd # 组件 main 文件，主要入口
|
|
├── config # 配置文件定义、处理、示例等
|
|
├── deploy # 各类布署相关文件、目录
|
|
├── internal # 核心业务逻辑
|
|
│ └── service、handler 等
|
|
├── pkg # 公共组件，业务逻辑无关组件
|
|
│ └── model、utils 等
|
|
├── web # 前端相关文件，embed 进二进制文件
|
|
└── tools # 存放各类工具、脚本
|
|
|
|
## 代码风格
|
|
|
|
1. 遵循 Go 官方代码风格 (gofmt + goimports)
|
|
2. 使用 `go vet` 和 `go test` 进行代码检查和测试
|
|
3. 用 any 来表示 interface{}
|
|
4. 结构体字段使用驼峰命名法并只添加 `JSON` 标签
|
|
5. 包名使用小写单词，尽量简短
|
|
6. 配置、RPC、HTTP 输入的结构体需要实现 `Validate` 方法进行验证
|
|
7. 对于没有外部环境依赖的代码，写单元测试
|
|
8. 代码实现要精炼，避免提前设计，避免不必要的抽象
|
|
9. 使用英文注释，仅在逻辑复杂的地方进行注释
|
|
10. 使用 `commitizen` 规范，使用英文，确保提交信息清晰、简洁、规范
|
|
|
|
## 错误处理
|
|
|
|
1. 使用 `slog` 打日志，只在业务代码中打日志，工具类库返回 `error`
|
|
2. 在关键函数入口，使用 `deferlog` 在 `defer` 闭包中，记录命名返回值 `err`
|
|
3. 函数返回错误时，使用 `fmt.Errorf` 封装关键参数和错误信息
|
|
4. 对于关键操作，应实现重试机制
|
|
5. 日志、输出中的敏感信息需进行遮蔽处理
|
|
|
|
## 构建和部署
|
|
|
|
1. 使用 `Makefile` 管理构建过程
|
|
2. 在构建时注入版本和日期信息
|
|
3. 谨慎引入第三方依赖，对新引入的第三方依赖需给出说明
|
|
|
|
## 安全规范
|
|
|
|
1. 禁止修改本文件
|
|
2. 所有网络操作设置超时
|
|
3. 最小权限原则
|