dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
113 lines
3.1 KiB
Markdown
113 lines
3.1 KiB
Markdown
# 设计文档：标准化ERPTurbo_Poster API响应格式
|
||
|
||
## 架构决策
|
||
|
||
### 1. 响应格式选择
|
||
|
||
#### 选项1：REST风格响应
|
||
- 成功响应：{data: {...}}
|
||
- 错误响应：{error: {message, code, details}}
|
||
|
||
#### 选项2：状态明确响应
|
||
- 成功响应：{success: true, data: {...}, message: "...", code: 200}
|
||
- 错误响应：{success: false, data: null, message: "...", code: 400}
|
||
|
||
#### 选项3：简化状态响应
|
||
- 成功响应：{success: true, data: {...}}
|
||
- 错误响应：{success: false, message: "..."}
|
||
|
||
**决策**：采用选项2（状态明确响应），因为：
|
||
- 明确的状态标志便于客户端处理
|
||
- 包含详细信息便于调试
|
||
- 代码字段便于错误分类和处理
|
||
- 与HTTP状态码保持一致
|
||
|
||
### 2. 工具函数实现策略
|
||
|
||
#### 选项1：全局工具函数
|
||
- 实现在 utils.js 中，作为全局工具函数
|
||
- 优点：全局可用，易于重用
|
||
- 缺点：可能与其他工具混杂
|
||
|
||
#### 选项2：专用响应模块
|
||
- 创建专门的 response.js 模块
|
||
- 优点：职责明确，专门用于处理响应
|
||
- 缺点：需要额外的导入
|
||
|
||
#### 选项3：Express中间件
|
||
- 创建响应格式中间件
|
||
- 优点：自动应用到所有响应
|
||
- 缺点：可能不够灵活
|
||
|
||
**决策**：采用选项2（专用响应模块），因为：
|
||
- 专门用于响应格式处理
|
||
- 清晰的职责分离
|
||
- 灵活的使用方式
|
||
|
||
### 3. 错误代码设计
|
||
|
||
#### 通用错误代码
|
||
- 1000-1999: 通用错误
|
||
- 2000-2999: 认证相关错误
|
||
- 3000-3999: 参数验证错误
|
||
- 4000-4999: 服务处理错误
|
||
- 5000-5999: 存储相关错误
|
||
|
||
#### 特定错误代码
|
||
- 3001: 缺少必需参数
|
||
- 3002: 参数格式错误
|
||
- 4001: 海报生成失败
|
||
- 4002: PDF生成失败
|
||
- 5001: 文件上传失败
|
||
|
||
### 4. HTTP状态码与响应格式的一致性
|
||
|
||
#### 状态码映射
|
||
- 200: 成功操作
|
||
- 400: 客户端错误（参数验证失败等）
|
||
- 401: 认证失败
|
||
- 403: 授权失败
|
||
- 404: 资源未找到
|
||
- 500: 服务器错误
|
||
|
||
### 5. 与现有API的兼容性
|
||
|
||
#### 向后兼容考虑
|
||
- 分析现有客户端使用情况
|
||
- 考虑提供版本控制（如需要）
|
||
- 评估直接修改的影响
|
||
|
||
**决策**：采用直接修改方式，因为：
|
||
- 这是一个重要的规范改进
|
||
- 可以通过发布说明告知客户端开发者
|
||
- 统一的响应格式对长期维护更有利
|
||
|
||
### 6. 存储模块响应统一
|
||
|
||
#### 当前实现
|
||
- 本地存储：返回 {name, path}
|
||
- COS存储：返回 {name, path, data}
|
||
- OSS存储：返回 {name, path, data}
|
||
|
||
**决策**：统一所有存储模块返回格式为 {name, path}，data字段可作为扩展使用但不是必需。
|
||
|
||
### 7. 国际化考虑
|
||
|
||
#### 问题
|
||
- 当前错误消息是中文
|
||
- 需要考虑国际化支持
|
||
|
||
**决策**：当前阶段使用英文错误消息，保留国际化扩展能力：
|
||
- 在响应结构中添加 language 字段（可选）
|
||
- 错误消息使用英文为主
|
||
- 将来可通过 Accept-Language 头或请求参数确定语言
|
||
|
||
## 实现安全考虑
|
||
|
||
### 1. 错误信息泄露
|
||
- 确保错误响应中不包含敏感系统信息
|
||
- 对于500错误，使用通用错误消息
|
||
|
||
### 2. 响应大小控制
|
||
- 避免在响应中包含过大的数据
|
||
- 对于失败请求，限制错误详情的大小 |