第 6 章

开发常识

掌握不同语言的代码规范、工具配置和最佳实践，建立专业的开发习惯，提升代码质量和团队协作效率。

使用 Sequential Thinking 学习开发常识

开发常识涉及多个方面，使用结构化思考方法可以帮助你系统掌握：

1
代码规范
不同语言的命名、格式、注释规范
2
工具配置
ESLint、Prettier、格式化工具的实际配置
3
最佳实践
错误处理、日志、性能、安全等实践
4
持续改进
代码审查、质量指标、技术债务管理

代码规范

统一的代码规范让代码更易读、易维护，是团队协作的基础。不同语言有不同的规范，下面我们按语言分类介绍。

命名规范

变量/函数
camelCase
getUserName, calculateTotal
类/组件
PascalCase
UserProfile, LoginForm
常量
UPPER_SNAKE_CASE
MAX_RETRY_COUNT, API_BASE_URL
文件
kebab-case
user-service.ts, login-form.tsx

ESLint 配置

推荐使用 Airbnb 或 TypeScript ESLint 配置。

.eslintrc.json（Airbnb + TypeScript）：
{
  "extends": [
    "airbnb-base",
    "airbnb-typescript/base",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json"
  },
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "import/prefer-default-export": "off",
    "max-len": ["error", { "code": 100 }]
  }
}

Prettier 配置

.prettierrc：
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always"
}

TypeScript 严格模式

tsconfig.json（严格模式）：
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

React 规范

  • • 使用函数组件和 Hooks，避免类组件
  • • Props 使用 TypeScript 接口定义
  • • 组件命名使用 PascalCase
  • • 使用 React.memo 优化性能（如需要）
  • • 自定义 Hooks 以 `use` 开头

其他语言快速参考

Rust
  • • rustfmt（格式化）
  • • clippy（代码检查）
  • • snake_case 命名
C#
  • • dotnet format
  • • EditorConfig
  • • PascalCase 命名
Swift/Kotlin/Dart
  • • Swift: SwiftLint
  • • Kotlin: ktlint
  • • Dart: dart format

版本控制

Git 是现代开发的标准工具。掌握 Git 工作流、分支策略和代码审查流程，是团队协作的基础。

分支策略

Git Flow
• main：生产环境
• develop：开发分支
• feature/*：功能分支
• release/*：发布分支
• hotfix/*：热修复
GitHub Flow
• main：主分支
• feature/*：功能分支
• 通过 PR 合并
• 适合持续部署
GitLab Flow
• main：主分支
• 环境分支（staging、production）
• 上游优先原则

提交信息规范（Conventional Commits）

格式：<type>(<scope>): <subject>
feat(auth): 添加用户登录功能
fix(api): 修复数据查询性能问题
docs(readme): 更新安装说明
refactor(utils): 重构日期格式化函数
feat
新功能
fix
修复 Bug
docs
文档更新
style
代码格式
refactor
重构
test
测试
chore
构建/工具
perf
性能优化

Git Hooks 配置

pre-commit Hook
# 提交前运行 lint 和格式化检查
npm run lint
npm run format:check
commit-msg Hook
# 检查提交信息格式
npx commitlint --edit $1

💡 使用 husky（Node.js）或 pre-commit（Python）管理 Git Hooks

代码审查流程

1创建功能分支，完成开发并提交代码
2创建 Pull Request，填写 PR 描述和检查清单
3代码审查者审查代码（功能、性能、安全、可维护性）
4根据反馈修改代码，重新提交
5审查通过后合并到主分支

依赖管理

合理管理项目依赖，确保项目的可维护性和安全性。不同语言有不同的依赖管理方式。

语义化版本（SemVer）

主版本号（MAJOR）
不兼容的 API 修改
2.0.0
次版本号（MINOR）
向下兼容的功能新增
1.2.0
修订号（PATCH）
向下兼容的问题修正
1.2.3
版本范围：^1.2.3（允许 1.x.x，不允许 2.0.0）、~1.2.3（允许 1.2.x，不允许 1.3.0）

锁定文件管理

Node.js
  • • package-lock.json（npm）
  • • yarn.lock（yarn）
  • • pnpm-lock.yaml（pnpm）
  • • 提交到版本控制，确保一致性
Python
  • • requirements.txt（pip）
  • • poetry.lock（Poetry）
  • • Pipfile.lock（Pipenv）
  • • 使用虚拟环境隔离依赖

依赖安全审计

Node.js
npm audit
npm audit fix
yarn audit
pnpm audit
Python
pip-audit
safety check
bandit（代码安全检查）

💡 使用 Dependabot 或 Renovate 自动更新依赖和安全补丁

依赖更新策略

  • • 定期更新：每月检查一次过时依赖
  • • 安全优先：优先更新有安全漏洞的依赖
  • • 测试驱动：更新后运行完整测试套件
  • • 渐进式更新：一次更新一个主要依赖，避免大规模变更
  • • 文档记录：记录重大依赖更新和迁移步骤

错误处理规范

良好的错误处理让程序更健壮，用户体验更好。不同语言有不同的错误处理模式。

错误类型分类

业务错误
  • • 用户输入错误
  • • 业务规则违反
  • • 返回友好的错误提示
系统错误
  • • 数据库连接失败
  • • 文件系统错误
  • • 记录详细日志
网络错误
  • • API 调用失败
  • • 超时错误
  • • 实现重试机制

错误处理模式

TypeScript/JavaScript/Python/Java：
try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  logger.error('操作失败', { error });
  throw new BusinessError('用户友好的错误信息');
}

错误处理最佳实践

  • • 明确错误类型：定义清晰的错误类型和错误码
  • • 记录错误日志：记录完整的错误信息和上下文
  • • 用户友好提示：向用户显示友好的错误信息，隐藏技术细节
  • • 错误恢复：提供重试、降级等恢复机制
  • • 错误边界：使用错误边界（React）或中间件（Express）统一处理错误

日志规范

良好的日志记录是调试和监控的基础。结构化日志让日志更易分析和处理。

日志级别

DEBUG
详细调试信息
开发调试
INFO
一般信息
正常操作
WARN
警告信息
潜在问题
ERROR
错误信息
错误但可恢复
FATAL
致命错误
系统无法继续

结构化日志（JSON 格式）

示例：
{
  "timestamp": "2025-01-27T10:30:00Z",
  "level": "ERROR",
  "message": "用户登录失败",
  "context": {
    "userId": "12345",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0..."
  },
  "error": {
    "type": "AuthenticationError",
    "message": "密码错误",
    "stack": "..."
  },
  "requestId": "req-abc123"
}

日志上下文

必需字段
  • • timestamp：时间戳
  • • level：日志级别
  • • message：日志消息
  • • requestId：请求 ID（追踪）
可选字段
  • • userId：用户 ID
  • • operation：操作类型
  • • duration：操作耗时
  • • metadata：额外元数据

敏感信息脱敏

  • • 密码：永远不要记录密码，使用 *** 替代
  • • Token：只记录 Token 的前几位和后几位
  • • 身份证号：脱敏处理，只显示部分数字
  • • 银行卡号：只显示后 4 位
  • • 邮箱：可以考虑部分脱敏（如：u***@example.com）

性能优化

性能优化是持续的过程。从代码层面到架构层面，都有优化空间。

代码性能优化

算法优化
  • • 选择合适的数据结构（HashMap vs List）
  • • 避免嵌套循环，使用索引或 Map
  • • 使用缓存避免重复计算
  • • 时间复杂度分析（O(n) vs O(n²)）
前端优化
  • • 代码分割和懒加载
  • • 图片优化（WebP、懒加载）
  • • 使用 React.memo 避免不必要的重渲染
  • • 虚拟滚动（长列表）

数据库查询优化

索引优化
  • • 为常用查询字段添加索引
  • • 避免过度索引（影响写入性能）
  • • 使用复合索引优化多字段查询
  • • 定期分析查询计划（EXPLAIN）
查询优化
  • • 避免 SELECT *，只查询需要的字段
  • • 使用分页避免一次性加载大量数据
  • • 使用 JOIN 替代多次查询
  • • 避免 N+1 查询问题

缓存策略

内存缓存
  • • 本地缓存（Map、LRU Cache）
  • • 适合热点数据
  • • 注意内存限制
Redis
  • • 分布式缓存
  • • 设置过期时间
  • • 缓存穿透/击穿/雪崩防护
CDN
  • • 静态资源加速
  • • 图片、CSS、JS 文件
  • • 边缘节点缓存

性能监控

  • • APM 工具：New Relic、Datadog、Sentry（性能监控）
  • • 性能分析：Chrome DevTools、Python cProfile、Go pprof
  • • 指标监控：响应时间、吞吐量、错误率、资源使用率
  • • 告警机制：设置性能阈值，超过阈值自动告警

安全最佳实践

安全不是可选项，而是必须项。从代码层面到部署层面，都需要考虑安全问题。

输入验证和清理

前端验证
  • • 使用 Zod、Yup 等库验证表单输入
  • • 客户端验证提升用户体验
  • • 但永远不要只依赖前端验证
后端验证
  • • 所有输入都必须验证
  • • 使用白名单而非黑名单
  • • 清理和转义用户输入

常见攻击防护

SQL 注入
  • • 使用参数化查询（Prepared Statements）
  • • 使用 ORM（Prisma、TypeORM）
  • • 永远不要拼接 SQL 字符串
XSS（跨站脚本）
  • • 输出转义（React 自动转义）
  • • 使用 Content Security Policy（CSP）
  • • 避免使用 dangerouslySetInnerHTML
CSRF（跨站请求伪造）
  • • 使用 CSRF Token
  • • SameSite Cookie 属性
  • • 验证 Referer Header
敏感数据加密
  • • 密码使用 bcrypt、Argon2 哈希
  • • 传输使用 HTTPS（TLS）
  • • 存储敏感数据加密

密钥管理

环境变量
  • • 使用 .env 文件（不提交到 Git）
  • • 使用 .env.example 作为模板
  • • 生产环境使用密钥管理服务
密钥管理服务
  • • AWS Secrets Manager
  • • HashiCorp Vault
  • • Azure Key Vault
  • • 定期轮换密钥

OWASP Top 10 防护

1.注入攻击（SQL、NoSQL、命令注入）
2.失效的身份认证
3.敏感数据泄露
4.XML 外部实体（XXE）
5.失效的访问控制
6.安全配置错误
7.XSS 跨站脚本
8.不安全的反序列化
9.使用含有已知漏洞的组件
10.不足的日志记录和监控

代码审查

代码审查是保证代码质量的重要环节。建立清晰的审查流程和清单，让审查更高效。

审查清单

功能
  • ☐ 功能是否符合需求
  • ☐ 边界情况是否处理
  • ☐ 错误处理是否完善
  • ☐ 测试是否充分
性能
  • ☐ 是否有性能问题
  • ☐ 数据库查询是否优化
  • ☐ 是否有内存泄漏
  • ☐ 缓存使用是否合理
安全
  • ☐ 输入验证是否完整
  • ☐ 敏感信息是否泄露
  • ☐ 权限检查是否正确
  • ☐ 依赖是否有安全漏洞
可维护性
  • ☐ 代码是否清晰易读
  • ☐ 命名是否规范
  • ☐ 注释是否充分
  • ☐ 是否遵循项目规范

审查最佳实践

及时审查：PR 创建后尽快审查，避免阻塞开发
建设性反馈：指出问题并提供改进建议，而非只批评
小批量审查：每次审查的代码量控制在 400 行以内
自动化检查：使用 CI/CD 自动检查格式、测试、安全

持续改进

代码质量不是一次性的工作，而是持续改进的过程。建立质量指标和监控机制。

代码质量指标

圈复杂度
  • • 衡量代码复杂度
  • • 目标：< 10
  • • 工具：SonarQube、CodeClimate
代码覆盖率
  • • 测试覆盖的代码比例
  • • 目标：> 80%
  • • 工具：Jest、Coverage.py、JaCoCo
技术债务
  • • 代码异味、重复代码
  • • 定期重构
  • • 工具：SonarQube

自动化检查（CI/CD 集成）

GitHub Actions 示例：
name: Code Quality

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
      - name: Install dependencies
        run: npm ci
      - name: Run linter
        run: npm run lint
      - name: Run tests
        run: npm test
      - name: Check coverage
        run: npm run test:coverage

技术债务管理

  • • 识别债务：使用工具自动识别代码异味和重复代码
  • • 优先级排序：根据影响范围和修复成本排序
  • • 定期重构：每个 Sprint 分配一定时间重构
  • • 记录债务：在 Issue 或技术债务清单中记录
  • • 避免新债务：代码审查时关注技术债务

学习成果

完成本章后，你将：

  • 1掌握不同语言的代码规范（TypeScript、Python、Java、Go 等）和工具配置
  • 2熟练使用 Git 进行版本控制，掌握分支策略和代码审查流程
  • 3理解依赖管理的重要性，掌握安全审计和更新策略
  • 4掌握错误处理和日志规范，提升代码健壮性
  • 5了解性能优化和安全最佳实践，编写高质量代码
  • 6建立代码审查和持续改进机制，提升团队代码质量
上一章：AI 适配架构范式下一章：界面交互