Instruction file imported from cyberspacesec/go-finger (
.cursor/rules/golang.mdc). Copyright stays with the author.
🐹 Golang 项目整体语法与开发规则
🔑 权限认证
权限认证逻辑统一实现于 middleware/auth_permission.go
- ✅ 统一调用：所有涉及权限判断的代码必须调用该中间件
- ✅ 技术支持：改动权限逻辑前必须阅读该文件并联系项目负责人
- ❌ 重复实现：禁止在其他位置自行编写权限校验函数
1. 代码复用原则 ♻️
永远优先复用已有函数、方法或公共库，避免代码重复
实施要求：
- ✅ 先搜索：使用
grep/rg/ IDE 全局搜索是否已有实现 - ✅ 先复用：直接调用或在原有函数中扩展实现
- ❌ 避免冗余：禁止复制已有函数代码到新位置
2. 模块化设计原则 🏗️
按照 Golang 常规分层架构组织代码：controller → service → repository → model
实施要求：
- ✅ 功能归类：业务功能对应到合适的包（package）
- ✅ 分层明确：HTTP 路由逻辑只写到
controller，业务处理在service，数据库访问在repository - ✅ 职责单一：一个包/文件只负责单一职责
- ❌ 随意放置：禁止贪图方便将业务逻辑直接写到
main.go
3. 严格按设计文档实现 📋
所有业务逻辑必须对照设计文档实现，不得自行添加不在需求中的功能
实施要求：
- ✅ 需求对照：功能实现时必须确认对应的文档需求点
- ✅ 范围控制：不得超出设计范围
- ✅ 文档更新：如需变更，必须先更新设计文档并获批准
- ❌ 随意扩展：禁止加“便民”或调试用功能到正式代码中
4. API 接口稳定性 🔒
所有公开 API 接口（HTTP / gRPC）保持稳定，不得未经批准修改
实施要求：
- ✅ 明确授权：接口修改必须经项目负责人同意
- ❌ 破坏性修改：禁止直接修改请求结构、响应结构或方法名
- ✅ 版本管理：需要修改时，必须新增版本（如
/v2/）保留旧版本稳定
5. 文档创建限制 📝
仅在明确需求下编写 .md 或 .doc 文档，避免冗余文档
实施要求：
- ✅ 按需编写：仅在需求提出或版本交付时编写
- ✅ 内容精准：文档必须与实际代码行为一致
- ❌ 自动生成：不要随意生成不必要的 API 文档或流程图
6. 代码唯一性原则 🔄
禁止在不同包中保留相同功能的重复实现
实施要求：
- ✅ 统一引入：使用单一实现的包引用，避免分散多处
- ✅ 及时清理：发现重复逻辑必须立即删除冗余版本
- ❌ 容忍重复：禁止因迁移或重构遗留两套功能代码
7. Golang 语法与编码规范 📏
统一采用 Go 官方标准与团队约定的代码格式
实施要求：
- ✅ 代码格式化：提交前必须运行
go fmt ./... - ✅ 错误处理：错误返回值必须显式处理，不得忽略
_式丢弃 - ✅ 命名规则：
- 包名：小写单词，不使用下划线，例如
auth,user - 常量：
const MaxRetry = 3 - 函数：导出函数首字母大写，内部函数首字母小写，例如
GetUser()/getUser()
- 包名：小写单词，不使用下划线，例如
- ✅ 结构体标签统一：JSON 序列化统一为小写加蛇形，例如：
type User struct { ID int `json:"id"` UserName string `json:"user_name"` } - ✅ 依赖管理：使用 Go Modules (
go.mod)，禁止使用GOPATH模式 - ✅ 日志格式统一：使用团队统一的日志库（如
logrus或zap），禁止直接fmt.Println
8. 回答原则 🇨🇳
所有项目相关的交流、注释及提交说明必须使用简体中文
实施要求：
- ✅ 统一语言：代码注释、提交 Commit 信息、文档均用简体中文（技术名词可保留英文）
- ✅ 简洁清晰：表达明确，不使用模糊描述
- ❌ 中英混用：除保留技术术语外禁止中英文混合
📌 执行建议
- 开发前：搜索已有实现 → 复用 → 按设计文档确认需求 → 确定所属包
- 开发中：遵守分层，保持代码职责单一
- 提交前：
go fmt→ 检查 API 稳定性 → 清理冗余代码 - 维护时：统一版本管理，接口变更需批准，重复功能立即合并
- 回答时：统一使用中文回答所有的问题，注释也采用中文