4e5147fb13
All checks were successful
Backend Deploy (Go + Docker) / deploy (push) Successful in 1m29s
64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
---
|
||
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. 成功响应
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"replies": [...] // 具体的业务数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 失败响应（业务报错）
|
||
* `code`: > 200 的自定义业务状态码（例如 `4001` 表示参数错误，`4003` 表示权限不足）。
|
||
* `message`: 面向前端的友好提示。
|
||
```json
|
||
{
|
||
"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` 保护。
|
||
* **触发器**: 创建触发器时必须先检查是否存在，避免重复定义导致部署中断。
|