dev-playbooks-cn 1.0.0

package/skills/devbooks-coder/references//347/274/226/347/240/201/351/243/216/346/240/274/347/273/206/345/210/231.md

@@ -0,0 +1,351 @@
+# 编码风格细则
+
+借鉴 VS Code 的 `guidelines/CODING_GUIDELINES.md`，本文档定义了代码风格的具体规范。
+
+---
+
+## 1) 命名规范
+
+### TypeScript/JavaScript
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 类名 | PascalCase | `UserService`, `HttpClient` |
+| 接口名 | PascalCase（无 I 前缀） | `User`, `Config` |
+| 函数名 | camelCase | `getUserById`, `parseConfig` |
+| 变量名 | camelCase | `userName`, `isActive` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `API_URL` |
+| 私有成员 | 下划线前缀 | `_cache`, `_disposed` |
+| 布尔变量 | is/has/can/should 前缀 | `isValid`, `hasPermission` |
+
+### 文件命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 组件文件 | PascalCase | `UserProfile.tsx` |
+| 工具文件 | camelCase | `stringUtils.ts` |
+| 测试文件 | 源文件名 + `.test` | `userService.test.ts` |
+| 类型文件 | 源文件名 + `.types` | `api.types.ts` |
+
+---
+
+## 2) 代码组织
+
+### 导入顺序
+
+```typescript
+// 1. Node.js 内置模块
+import * as fs from 'fs';
+import * as path from 'path';
+
+// 2. 第三方库（按字母排序）
+import { Observable } from 'rxjs';
+import * as vscode from 'vscode';
+
+// 3. 内部模块（按层级排序：base → platform → 业务）
+import { Disposable } from '@/base/common/lifecycle';
+import { IConfigService } from '@/platform/config/common/config';
+
+// 4. 相对导入（按距离排序：远 → 近）
+import { UserModel } from '../models/user';
+import { formatDate } from './utils';
+
+// 5. 类型导入（单独分组）
+import type { User, Config } from '../types';
+```
+
+### 导出顺序
+
+```typescript
+// 1. 类型导出
+export type { User, Config };
+export interface IService { ... }
+
+// 2. 常量导出
+export const DEFAULT_CONFIG = { ... };
+
+// 3. 函数导出
+export function createUser() { ... }
+
+// 4. 类导出
+export class UserService { ... }
+
+// 5. 默认导出（仅用于模块入口）
+export default UserService;
+```
+
+---
+
+## 3) 函数规范
+
+### 函数长度
+
+- **推荐**：≤ 30 行
+- **警告**：30-50 行
+- **禁止**：> 50 行（必须拆分）
+
+### 参数数量
+
+- **推荐**：≤ 3 个
+- **警告**：4-5 个
+- **禁止**：> 5 个（使用对象参数）
+
+```typescript
+// 违规：参数过多
+function createUser(name: string, email: string, age: number,
+                    role: string, department: string, manager: string) { ... }
+
+// 正确：使用对象参数
+interface CreateUserOptions {
+  name: string;
+  email: string;
+  age: number;
+  role: string;
+  department: string;
+  manager: string;
+}
+
+function createUser(options: CreateUserOptions) { ... }
+```
+
+### 返回值
+
+```typescript
+// 违规：多处返回，难以追踪
+function process(data: Data): Result {
+  if (!data) return null;
+  if (data.type === 'A') return processA(data);
+  if (data.type === 'B') return processB(data);
+  return processDefault(data);
+}
+
+// 正确：单一出口，清晰的控制流
+function process(data: Data): Result {
+  let result: Result;
+
+  if (!data) {
+    result = null;
+  } else if (data.type === 'A') {
+    result = processA(data);
+  } else if (data.type === 'B') {
+    result = processB(data);
+  } else {
+    result = processDefault(data);
+  }
+
+  return result;
+}
+```
+
+---
+
+## 4) 类型安全
+
+### 禁止的模式
+
+```typescript
+// 禁止：any 类型
+function process(data: any) { ... }  // ❌
+
+// 正确：使用 unknown 或具体类型
+function process(data: unknown) { ... }  // ✓
+function process(data: Record<string, unknown>) { ... }  // ✓
+
+// 禁止：类型断言跳过检查
+const user = {} as User;  // ❌
+
+// 正确：构造完整对象
+const user: User = {
+  id: '1',
+  name: 'John',
+  email: 'john@example.com'
+};  // ✓
+
+// 禁止：非空断言
+const name = user!.name;  // ❌
+
+// 正确：显式检查
+const name = user?.name ?? 'default';  // ✓
+```
+
+### 推荐的模式
+
+```typescript
+// 使用类型守卫
+function isUser(obj: unknown): obj is User {
+  return typeof obj === 'object' && obj !== null && 'id' in obj;
+}
+
+// 使用 satisfies 运算符（TypeScript 4.9+）
+const config = {
+  host: 'localhost',
+  port: 3000
+} satisfies Config;
+
+// 使用 const 断言
+const ROLES = ['admin', 'user', 'guest'] as const;
+type Role = typeof ROLES[number];
+```
+
+---
+
+## 5) 错误处理
+
+### 异常规范
+
+```typescript
+// 禁止：吞掉异常
+try {
+  await riskyOperation();
+} catch (e) {
+  // 什么都不做 ❌
+}
+
+// 正确：记录并重新抛出或处理
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Operation failed', e);
+  throw new OperationError('Failed to complete operation', { cause: e });
+}
+
+// 正确：明确处理
+try {
+  await riskyOperation();
+} catch (e) {
+  if (e instanceof NetworkError) {
+    return fallbackValue;
+  }
+  throw e;
+}
+```
+
+### 错误类定义
+
+```typescript
+// 创建自定义错误类
+class ApplicationError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+class ValidationError extends ApplicationError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'VALIDATION_ERROR', details);
+  }
+}
+```
+
+---
+
+## 6) 注释规范
+
+### 何时添加注释
+
+| 场景 | 是否需要注释 |
+|------|--------------|
+| 代码"做什么"（what） | ❌ 代码自解释 |
+| 代码"为什么"（why） | ✓ 需要注释 |
+| 复杂算法 | ✓ 需要注释 |
+| 临时解决方案 | ✓ 需要注释 + TODO |
+| 公共 API | ✓ 需要 JSDoc |
+
+### JSDoc 格式
+
+```typescript
+/**
+ * 根据用户 ID 获取用户信息
+ *
+ * @param id - 用户的唯一标识符
+ * @returns 用户对象，如果不存在则返回 undefined
+ * @throws {ValidationError} 当 id 格式无效时
+ *
+ * @example
+ * ```typescript
+ * const user = await getUserById('123');
+ * if (user) {
+ *   console.log(user.name);
+ * }
+ * ```
+ */
+async function getUserById(id: string): Promise<User | undefined> {
+  // ...
+}
+```
+
+### TODO 格式
+
+```typescript
+// TODO(#123): 优化查询性能，当前实现在大数据量时较慢
+// FIXME(#456): 修复边界条件处理
+// HACK: 临时解决方案，等待上游库修复后移除
+// NOTE: 这里使用了非标准 API，需要在 Node 18+ 环境运行
+```
+
+---
+
+## 7) 异步代码
+
+### Promise vs async/await
+
+```typescript
+// 推荐：使用 async/await
+async function fetchUserData(id: string): Promise<UserData> {
+  const user = await getUser(id);
+  const profile = await getProfile(user.profileId);
+  return { user, profile };
+}
+
+// 并行执行
+async function fetchAllData(ids: string[]): Promise<UserData[]> {
+  return Promise.all(ids.map(id => fetchUserData(id)));
+}
+
+// 避免：混用 then 和 await
+async function badExample() {
+  const user = await getUser(id);
+  return getProfile(user.profileId).then(p => ({ user, profile: p })); // ❌
+}
+```
+
+### 取消支持
+
+```typescript
+// 使用 AbortController
+async function fetchWithTimeout(
+  url: string,
+  timeoutMs: number
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+```
+
+---
+
+## 8) 检查清单
+
+代码提交前确认：
+
+- [ ] 命名符合规范（PascalCase/camelCase）
+- [ ] 导入顺序正确
+- [ ] 函数长度 ≤ 30 行
+- [ ] 参数数量 ≤ 3 个
+- [ ] 无 `any` 类型
+- [ ] 无 `@ts-ignore`
+- [ ] 异常已正确处理
+- [ ] 复杂逻辑有注释
+- [ ] 公共 API 有 JSDoc
+- [ ] TODO 关联 issue 编号