From 2471f970662dbf4c0fb4c7a535989399c69b1ed7 Mon Sep 17 00:00:00 2001 From: wonder Date: Mon, 25 May 2026 14:31:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=90=8E=E7=AB=AF?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E8=A1=A5=E5=85=85=E6=97=A5=E5=BF=97?= =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/backend.md | 74 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 56 insertions(+), 18 deletions(-) diff --git a/docs/backend.md b/docs/backend.md index 947357e..63be3ff 100644 --- a/docs/backend.md +++ b/docs/backend.md @@ -14,34 +14,32 @@ backend/internal/ │ ├── health.go # [已有] 健康检查 │ ├── register.go # [已有] 用户注册（handler 骨架 + 参数校验） │ ├── login.go # [已有] 用户登录（handler 骨架 + 参数校验） -│ ├── project.go # 工程 CRUD + 任务列表 -│ ├── generate.go # 生成任务提交 / 查询 / WebSocket -│ ├── project_style.go # 工程风格 CRUD +│ ├── generate.go # [已有] 素材生成（异步管线 + 任务查询） +│ ├── edit.go # [已有] 图片编辑 +│ ├── prompt.go # [已有] 提示词优化 │ └── storage.go # [已有] 素材下载（重定向到七牛云 CDN） ├── service/ # 业务逻辑层 │ ├── pipeline.go # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter │ ├── nodes.go # [已有] 管线四个节点的实现（每个节点单一职责） │ ├── types.go # [已有] 管线输入/状态/输出的显式结构体定义 -│ ├── inference.go # [已有] AI 推理 API 调用封装（当前为 mock 实现） +│ ├── inference.go # [已有] AI 推理 API 调用封装（文生图 + 图片编辑） +│ ├── prompt_agent.go # [已有] LLM 提示词优化 Agent │ ├── pipeline_test.go # [已有] 管线测试（happy path / 重试 / 降级 / 风格合并） -│ ├── auth.go # 用户认证：注册、登录、JWT 签发与校验 -│ ├── project_style.go # 工程风格管理 & 风格合并逻辑 +│ ├── auth.go # [已有] 用户认证：注册、登录、JWT 签发与校验 │ └── storage.go # [已有] 七牛云对象存储：上传、下载 URL 生成、删除 ├── model/ # 数据模型 / DTO │ ├── response.go # [已有] 统一响应 -│ ├── user.go # [已有] 用户模型 -│ ├── task.go # 生成任务 & 素材 -│ └── style.go # 工程风格 & 任务风格覆盖 -├── middleware/ # 中间件 -│ ├── logger.go -│ ├── auth.go # JWT 认证中间件（从 Cookie 读取 Token） -│ └── ratelimit.go +│ └── user.go # [已有] 用户模型 +├── mildware/ # 中间件 +│ ├── logger.go # [已有] 请求日志 + Panic 恢复中间件（基于 slog） +│ └── auth.go # [已有] JWT 认证中间件 +├── logger/ # [已有] 日志包（基于 log/slog） +│ └── logger.go # 日志初始化、全局 logger、context 注入 ├── config/ # [已有] 配置 -│ └── config.go -├── queue/ # 异步任务队列 -│ └── jobqueue.go -└── cache/ # 缓存层（请求去重） - └── cache.go +│ ├── config.go +│ └── config.yml +└── db/ # [已有] 数据库初始化 + └── db.go ``` ## 分层原则 @@ -50,6 +48,46 @@ backend/internal/ - **service**：承载所有业务逻辑。`pipeline.go` 通过 Eino `compose.Graph` 编排四个节点；`nodes.go` 实现各节点逻辑；`types.go` 定义显式状态结构体。 - **model**：纯数据结构，不含业务逻辑。 +## 日志系统 + +基于 Go 标准库 `log/slog`，无需第三方依赖。 + +### 核心组件 + +- **`internal/logger/logger.go`**：日志初始化与 context 注入 + - `Init(level, format)` — 初始化全局 logger（level: debug/info/warn/error，format: text/json） + - `FromCtx(ctx)` — 从 context 提取带 request_id 的 logger + - `WithRequestID(ctx, id)` — 创建带 request_id 的 logger 并存入 context + +- **`internal/mildware/logger.go`**：HTTP 请求日志 + Panic 恢复中间件 + - `Logger()` — 为每个请求生成 request_id（注入 header `X-Request-ID`），记录 method/path/status/latency/client_ip + - `Recovery()` — 自定义 panic 恢复，记录 request 上下文和堆栈 + +### 日志级别使用规范 + +| 级别 | 场景 | +|------|------| +| Debug | 开发调试信息 | +| Info | 正常业务流程（API 调用、任务完成等） | +| Warn | 可恢复的异常（认证失败、LLM 回退模板等） | +| Error | 不可恢复的错误（API 调用失败、数据库错误等） | + +### 配置 + +```yaml +log: + level: info # debug / info / warn / error + format: text # text（开发）/ json（生产） +``` + +环境变量：`GEN2D_LOG_LEVEL`、`GEN2D_LOG_FORMAT` + +### 错误处理原则 + +- 服务端错误（5xx）：先用 `slog.Error` 记录完整错误（含 request_id），返回客户端通用描述 +- 客户端错误（4xx）：用 `slog.Warn` 记录，返回具体提示 +- 内部错误细节不泄露给客户端 + ## 多阶段生成管线 gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的三阶段管线，含质检不通过时的重优化分支。