第16章 工程实践

📖 《Gemini-Voyager 从入门到精通》系列连载

16.1 TypeScript 类型系统

项目严格使用 TypeScript，禁止使用 any 类型。

类型安全实践

┌─────────────────────────────────────────────────────────────────┐
│                    TypeScript 类型安全实践                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 禁止 any 类型                                              │
│   ✗ const value: any = getData();                            │
│   ✓ const value = getData() as Folder;                       │
│                                                                 │
│   2. Branded Types (区分语义类型)                              │
│   type FolderId = string & { readonly brand: unique symbol };  │
│   type ConversationId = string & { readonly brand: ... };      │
│                                                                 │
│   3. 类型守卫 (收窄 unknown 类型)                               │
│   function isFolder(x: unknown): x is Folder { ... }         │
│   if (isFolder(data)) { data.name /* 类型安全 */ }            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

16.2 测试策略

使用 Vitest 框架，遵循 TDD 工作流程。

TDD 流程

┌─────────────────────────────────────────────────────────────────┐
│                    TDD 工作流程                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 编写测试                                                   │
│   2. 运行测试 (预期失败)                                       │
│   3. 编写实现代码                                               │
│   4. 再次运行测试 (预期通过)                                   │
│   5. 重构代码                                                   │
│                                                                 │
│   命令:                                                         │
│   bun run test        - 运行所有测试                           │
│   bun run test:watch - 监听模式                               │
│   bun run test:coverage - 检查覆盖率                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

16.3 代码质量保障

完整的代码质量保障体系。

提交前检查

git commit -m "feat: add new feature"
        │
        ▼
   ESLint 检查: bun run lint
        │
        ▼
   TypeScript 检查: bun run typecheck
        │
        ▼
   测试检查: bun run test
        │
        ▼
   Commitlint 检查 (提交格式)

提交格式

<type>(<scope>): <description>

类型: feat, fix, refactor, docs, test, build, ci, perf, style, chore
示例: feat(folder): add drag and drop support

⏳ 下一部分将介绍实战篇