开发指南

开发流程

TDD 开发模式 ⭐ 优先采用

1. Red: 先写测试，运行看到失败
2. Green: 写最少代码让测试通过
3. Refactor: 重构代码，保持测试通过

开发流程

1. 后端: 先写测试 → 实现业务逻辑 → 添加路由测试 → 实现路由
2. 前端: 先写组件测试 → 实现组件 → 添加 hooks 测试 → 实现 hooks
3. 共享: 先写 schema 测试 → 定义 schemas

测试

运行测试

# 运行所有测试
pnpm test

# 运行特定包的测试
pnpm --filter server test
pnpm --filter web test

# 监听模式
pnpm --filter server test:watch

测试规范

• 测试文件：__tests__ 目录，与源码结构对应
• 命名：*.test.ts 或 *.spec.ts
• 工具：Vitest（后端）+ Vitest + React Testing Library（前端）
• Mock：使用 Vitest 的 vi.mock() 和 vi.fn()

代码规范

TypeScript

• 禁止使用 any 类型：必须使用明确的类型定义
• 优先使用类型推断，减少显式类型注解
• 使用 interface 定义对象类型
• 使用 type 定义联合类型、工具类型等

Git 提交规范

格式：类型(模块): 描述

类型: feat | fix | docs | refactor | test | chore | perf | ci

模块: auth | user | api | ui | config | deploy | deps | init

示例:

feat(auth): 添加用户登录功能
fix(api): 修复 CORS 错误
docs(readme): 更新部署文档

调试技巧

后端调试

# 使用 wrangler dev 进行调试
cd apps/server
pnpm dev

# 查看日志
wrangler tail

前端调试

• 使用浏览器开发者工具
• React DevTools
• TanStack Query DevTools

常见问题

端口冲突

如果端口被占用，可以修改：

• apps/web/vite.config.ts - Web 应用端口
• apps/auth-portal/vite.config.ts - 认证门户端口
• apps/server/wrangler.toml - 后端端口

数据库连接失败

• 检查 DATABASE_URL 或 ACCELERATE_URL 是否正确
• 确认数据库服务是否运行
• 查看 数据库文档