InsightReply/rules/backend-guidelines.md

description: InsightReply 后端 Go/API 编码规范与架构设计 globs: *.go, *.sql

InsightReply 后端 Go 编码与 API 设计规范

本文档定义了 InsightReply 后端服务（Golang）的架构风格、代码组织模式及统一的 API 响应标准。

一、 整体架构模式

后端服务采用 清晰架构 (Clean Architecture / Domain-Driven Design 简化版) 进行分层，严禁跨层调用：

• cmd/server/: 应用入口，加载配置、初始化路由与数据库连接。
• internal/handler/ (或 controller/): 负责接收 HTTP 请求，解析参数，并将其转化为业务层需要的结构。
• internal/service/: 存放核心业务逻辑（如调用 LLM 生成评论的策略代码、热度计算公式的落地）。
• internal/repository/ (或 model/): 负责与 PostgreSQL 数据库交互（封装所有的 SQL / ORM 逻辑）。

二、 统一接口标准 (RESTful)

所有对外部浏览器和前端暴露的 HTTP JSON 接口，必须严格遵守统一的包装格式。

1. 成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "replies": [...] // 具体的业务数据
  }
}

2. 失败响应（业务报错）

• code: > 200 的自定义业务状态码（例如 4001 表示参数错误，4003 表示权限不足）。
• message: 面向前端的友好提示。

{
  "code": 4001,
  "message": "推文链接解析失败",
  "data": null
}

注：HTTP Status Code 应依然使用 400 Bad Request 或 500 Internal Server Error 匹配网络层的状态语义。

三、 Go 代码风格与规范

• 错误处理 (Error Handling):
  • 坚决避免到处写 err != nil 却只做透明抛出的行为，当错误发生时，使用 fmt.Errorf("doSomething failed: %w", err) 包装上游错误信息，以便追踪。
• 命名规范:
  • 包名 (package): 保持简短、全部小写、无下划线，不使用复数形式（如用 user 而非 users）。
  • 接口类型名 (interface): 通常以 -er 结尾（如 Reader, TweetFetcher）。
• 日志打印:
  • 关键的业务路径（如调用第三方 LLM API 失败）、恐慌恢复 (Panic Recovery)、定时任务失败必须有结构化的日志记录。

四、 数据库 (PostgreSQL) 规范

• 对于本项目的初步开发，推荐使用如 gorm 或 sqlx 进行快速的数据交互操作。
• 所有表名、字段名在 Go 结构体 (struct) 的 tag 中必须显式定义为下划线 (snake_case)。
• UUID 作为主键，禁止前端或外部服务自行生成传入，一律由 PostgreSQL gen_random_uuid() 或者服务端生成。
• 数据库迁移 (Migration):
  • 禁用自动迁移: 后端程序不再自动执行 Up() 迁移，所有变更需手动通过 MCP 或 DBA 工具执行。
  • 幂等性: 所有 SQL 脚本（如 CREATE INDEX, CREATE TABLE）必须包含 IF NOT EXISTS 保护。
  • 触发器: 创建触发器时必须先检查是否存在，避免重复定义导致部署中断。