通用开发规范
本文档包含适用于各类项目的通用开发规范，可复制到其他项目使用。
编码规范
基本原则
- 类型安全: 使用 TypeScript strict mode
- 明确类型: 函数必须有明确的类型注解
- 运行时验证: 使用 Zod 等工具验证外部输入
- 设计原则: 遵循 SOLID 原则
代码质量
- 代码格式化通过
- Lint 检查无错误
- TypeScript 类型检查通过
- 无安全漏洞
QA 循环流程
循环最多 5 次:
1. 构建项目 → 检查构建错误
2. Lint 检查 → 自动修复或报告
3. 类型检查 → 修复类型错误
4. 单元测试 → 修复失败用例
5. E2E 测试 → 修复失败用例
如果同一错误重复 3 次:
停止并报告根本问题
错误修复循环
while (存在错误):
1. 读取错误详情
2. 分类错误类型
3. 定位错误位置
4. 应用修复
5. 验证修复结果
6. 运行相关测试
if 同一错误重复 3 次:
报告给用户处理
break
错误分类
| 错误类型 | 处理方式 |
|---|---|
| 构建错误 | 检查依赖、配置、语法 |
| Lint 错误 | 自动修复或手动调整 |
| 类型错误 | 添加/修复类型定义 |
| 单元测试失败 | 修复代码或更新测试 |
| E2E 测试失败 | 检查 UI/API 集成 |
质量检查清单
提交代码前确认：
- 代码格式化通过
- Lint 检查无错误
- TypeScript 类型检查通过
- 单元测试全部通过
- E2E 测试全部通过
- 构建成功
- 无安全漏洞
E2E 测试规范
核心原则
- 测试真实功能，不仅是 UI 元素是否存在
- 配置依赖测试：如果功能依赖配置，测试必须验证配置是否正确加载
- 真实 API 测试：测试连接功能必须实际调用 API 并验证响应
测试检查清单
设置/配置相关功能测试必须包含：
- 配置文件是否存在检查
- 配置是否正确加载检查
- 必填字段是否有值检查
- 实际 API 连接测试（不仅是按钮可点击）
- 错误状态正确显示测试
- 成功状态正确显示测试
测试用例模板
// 错误的做法 - 只测试 UI
test('should have test button', async ({ page }) => {
await expect(page.locator('.test-button')).toBeVisible();
});
// 正确的做法 - 测试真实功能
test('should test connection and show result', async ({ page }) => {
await page.locator('.test-button').click();
await page.waitForTimeout(1000);
// 验证实际有响应
const result = page.locator('.connection-status');
await expect(result).toBeVisible();
// 验证响应内容合理
const text = await result.textContent();
expect(text).toMatch(/成功|失败|错误/);
});
常见错误
| 错误 | 原因 | 解决方法 |
|---|---|---|
| 测试通过但功能不工作 | 只测试了 UI 结构 | 添加功能验证测试 |
| 配置未加载 | 配置文件不存在 | 创建配置文件 |
| API 连接失败 | 未正确配置 | 检查配置项 |
异常处理规范
核心原则
编写任何代码前，必须先列出所有可能的异常情况，再编写处理逻辑。
异常分类检查清单
编写代码时按以下分类检查异常：
1. 输入验证
| 检查项 | 处理方式 |
|---|---|
| 必填参数为空 | 返回友好提示，说明缺少哪个参数 |
| 格式错误 | 验证 URL、邮箱、数字等格式，给出正确格式示例 |
| 类型不匹配 | 检查类型，返回期望的类型说明 |
| 值范围超限 | 检查数值范围、字符串长度等 |
2. 外部依赖
| 检查项 | 处理方式 |
|---|---|
| 网络连接失败 | 提示检查网络或目标地址 |
| 连接超时 | 提示检查网络或服务状态 |
| DNS 解析失败 | 提示检查域名是否正确 |
| 服务不可用 | 提示服务暂时不可用，建议稍后重试 |
| 认证失败 | 提示检查凭证是否正确或已过期 |
3. 响应处理
| 检查项 | 处理方式 |
|---|---|
| HTTP 4xx 错误 | 根据具体状态码给出对应提示 |
| HTTP 5xx 错误 | 提示服务器错误，建议稍后重试 |
| 响应格式错误 | 捕获解析异常，提示响应格式不符预期 |
| 响应为空 | 检查空值，给出默认值或提示 |
4. 业务逻辑
| 检查项 | 处理方式 |
|---|---|
| 资源不存在 | 明确指出哪个资源不存在 |
| 权限不足 | 提示缺少必要权限 |
| 状态冲突 | 提示当前状态不允许此操作 |
| 重复操作 | 检查幂等性，提示资源已存在 |
HTTP 状态码友好提示
| 状态码 | 含义 | 友好消息示例 |
|---|---|---|
| 400 | 请求格式错误 | "请求参数格式错误" |
| 401 | 未认证 | "请先登录" / "认证信息无效或已过期" |
| 403 | 无权限 | "您没有权限执行此操作" |
| 404 | 资源不存在 | "请求的资源不存在" |
| 409 | 冲突 | "资源已存在" / "数据版本冲突" |
| 429 | 请求过频 | "操作过于频繁，请稍后重试" |
| 500 | 服务器错误 | "服务器内部错误，请稍后重试" |
| 502 | 网关错误 | "服务暂时不可用" |
| 503 | 服务不可用 | "服务正在维护，请稍后重试" |
| 504 | 网关超时 | "请求超时，请稍后重试" |
错误消息原则
- 用户友好：用用户能理解的语言，不要暴露技术细节
- 具体明确：告诉用户具体哪里出错了、该怎么解决
- 区分场景：不同错误类型给出不同的提示
- 可操作：提示用户可以采取什么行动
示例对比
| 错误做法 | 正确做法 |
|---|---|
| "Error: ECONNREFUSED" | "无法连接到服务器，请检查地址是否正确" |
| "Invalid parameter" | "URL 格式错误，需要以 http:// 或 https:// 开头" |
| "JSON parse error" | "服务器响应格式错误，请稍后重试" |
| "401 Unauthorized" | "API Key 无效或已过期，请检查配置" |
代码注释规范
在涉及异常处理的函数头部，用注释列出处理规则：
/**
* XXX 功能
*
* 异常处理规则:
* 1. 参数为空 → 返回 "未配置 XXX"
* 2. 格式错误 → 返回 "XXX 格式无效，请检查 YYY"
* 3. 连接失败 → 返回 "无法连接，请检查 XXX"
* 4. 响应错误 → 返回具体错误信息
*/
前端表单处理规范
- 测试连接必须使用表单当前值，而不是已保存的配置值
- 表单提交前进行客户端验证，减少无效请求
- 显示加载状态，防止重复提交
- 错误提示要显示在相关字段附近
后端 API 处理规范
- 请求体解析要容错，解析失败使用默认值或返回友好错误
- 所有外部请求都要 try-catch
- 不要假设响应格式，解析响应也要 try-catch
- 区分 success 和 connected：
success: true表示 API 调用成功connected: true表示连接/功能正常
- 错误响应不要抛异常，返回正常响应体包含错误信息
开发注意事项
- 测试先行: 遵循 TDD 开发模式
- 错误重复: 同一错误 3 次需人工介入
- 服务依赖: E2E 测试需要相关服务运行中