engineering-best-practices-2026

工程最佳实践 — 2026 版

面向大模型和 AI 编码 Agent 的综合 SKILL.md。
在所列的所有技术栈中生成、审查或重构代码时，请遵循这些规则。

---

目录

1. 通用原则
2. Node.js
3. Next.js
4. NestJS
5. Java
6. Spring Boot
7. Python
8. Elixir
9. Phoenix
10. Erlang
11. Rust
12. Go（Golang）
13. React
14. Vue
15. Nuxt
16. Astro
17. SQL / NoSQL

---

通用原则

以下原则适用于下面的所有语言和框架。绝不可违反。

安全

• 默认采用零信任。 在每一层进行身份验证和授权，而不只是边缘层／中间件。
• 在边界处验证并清理所有输入（模式验证：Zod、Joi、class-validator、Pydantic 等）。
• 绝不记录敏感数据（密码、令牌、个人身份信息、银行卡号）。
• 所有传输均使用 TLS 1.3。强制使用 HTTPS；拒绝明文传输。
• 将密钥存储在环境变量或密钥管理器中（Vault、AWS Secrets Manager）。绝不将其提交到代码库。
• 默认应用 OWASP Top 10 缓解措施（注入、身份验证失效、XSS、CSRF、SSRF 等）。
• 固定依赖版本。每次推送时都在 CI 中运行 audit/trivy/snyk。
• 服务账户、数据库角色和 IAM 策略遵循最小权限原则。

性能

• 优化前先进行性能分析。使用 APM（OpenTelemetry、Jaeger、Zipkin）和结构化指标。
• I/O 密集型任务优先采用异步／非阻塞 I/O；CPU 密集型任务使用工作线程／进程。
• 在合适的层级积极使用缓存（CDN → 应用缓存 → 数据库查询缓存）。明确失效策略。
• 所有数据库都使用连接池。根据工作负载调整连接池大小。
• 避免 N+1 查询。使用预加载／DataLoader／批量获取。
• 为所有列表端点分页。绝不返回无界结果集。

幂等性

• 所有可重试且会修改数据的 HTTP 端点（POST、PUT、PATCH、DELETE）必须具备幂等性。
• 使用客户端提供或服务端生成的幂等键，并将其存储在带有 TTL 的去重表中。
• 将后台任务和消息消费者设计为幂等的（至少一次投递是常态）。

原子性与事务

• 将多步骤变更封装在数据库事务中。仅在全部成功时提交；发生任何错误时回滚。
• 在分布式系统中，使用 Saga 模式（编排或协同），而非分布式 2PC。
• 对高争用行应用乐观锁（version/updated_at 列）。
• 使用数据库级约束（UNIQUE、FK、CHECK）作为最后一道防线。

并发

• 避免共享可变状态。优先采用消息传递、不可变数据结构和 Actor。
• 使用语言原生并发原语（goroutine、BEAM 进程、虚拟线程、async/await）。
• 使用适当的同步机制保护共享状态（互斥锁、通道、STM、CRDT）。
• 针对背压进行设计：有界队列、熔断器和速率限制。

可观测性

• 输出结构化日志（JSON），包含关联 ID、跟踪 ID、严重级别和时间戳。
• 使用 OpenTelemetry 进行插桩：通过统一的 SDK 整合跟踪、指标和日志。
• 定义 SLO/SLAs；根据消耗速率而非单纯阈值触发告警。
• 每个服务都提供健康检查端点：/health（存活状态）和 /ready（就绪状态）。

无障碍（UI）

• 最低遵循 WCAG 2.2 AA。面向公众的产品以 AAA 为目标。
• 使用语义化 HTML 元素。不要滥用 <div> 和 <span>。
• 每个交互元素都必须支持键盘导航，并清晰显示焦点状态。
• 仅在语义化 HTML 无法满足需求时才提供 ARIA 角色／标签。
• 使用屏幕阅读器（NVDA、VoiceOver）和自动化工具（axe-core、Lighthouse）进行测试。
• 确保颜色对比度：普通文本 ≥ 4.5:1，大号文本 ≥ 3:1。

错误处理

• 在开发环境中快速失败并明确报错；在生产环境中优雅地处理失败。
• 切勿静默吞掉错误（catch(e) {}）。
• 返回结构化错误响应：{ code, message, details?, traceId }。
• 区分运行时错误（客户端错误、网络错误）和程序错误（缺陷）。
• 按语言使用类型化的错误层次结构；避免使用字符串类型的错误。

API 设计

• REST：遵循面向资源的设计；按语义使用 HTTP 动词；返回适当的状态码。
• 从一开始就为 API 进行版本控制（/v1/）。绝不破坏现有客户端。
• 使用 OpenAPI 3.1 / AsyncAPI 编写文档。将文档与代码放在一起（自动生成，而非手动编写）。
• GraphQL：限制查询深度和复杂度。使用 DataLoader 批量处理。
• 对所有公共端点实施速率限制。返回 429 和 Retry-After。

CI/CD

• 快速失败：lint → 类型检查 → 单元测试 → 集成测试 → 安全扫描 → 构建 → 部署。
• 强制启用分支保护；合并前必须通过 CI。
• 使用语义化版本控制（semver）。为发行版打标签。自动生成变更日志。
• 优先使用不可变制品（容器镜像使用 Git SHA 作为标签）。生产环境绝不使用 latest。

---

Node.js

基线：Node.js 22 LTS（Active）或 Node.js 24（Current）。避免使用已停止支持的版本。

项目结构

src/
  config/        # env validation (zod/envalid)
  routes/        # thin HTTP handlers
  services/      # business logic
  repositories/  # data access
  middleware/
  utils/
  types/

运行时与性能

• 在适用时使用 --enable-source-maps 和 --experimental-vm-modules。
• 根据容器 RAM 设置合适的 --max-old-space-size。
• 使用 worker_threads 执行 CPU 密集型任务；绝不阻塞事件循环。
• 使用 AsyncLocalStorage 存储请求级上下文（关联 ID）——绝不使用线程局部变量或全局变量。
• 优化前先使用 clinic.js（flame、bubbleprof、heap profiler）进行性能分析。
• 使用 pino 进行日志记录（最快的 JSON 日志记录器）；生产环境避免使用 console.log。

安全

• 在每个 Express/Fastify 应用中使用 helmet。明确配置 CSP——不要使用默认设置。
• 使用明确的允许列表配置 cors；生产环境中绝不设置 origin: '*'。
• 使用 express-rate-limit 或 @fastify/rate-limit 限制速率。多实例部署时使用 Redis 存储。
• 在请求体/参数/查询抵达业务逻辑之前，使用 Zod 或 Joi 验证所有请求体/参数/查询。
• 使用 argon2 或 bcrypt 进行密码哈希（绝不单独使用 md5、sha1 或 sha256）。
• 使用 DOMPurify（浏览器端）或 sanitize-html（服务端）清理 HTML 输出。
• 设置 NODE_ENV=production，以避免泄露冗长的错误信息。
• 审计依赖项：在 CI 中运行 npm audit --audit-level=high；使用 Dependabot 或 Renovate 自动化处理。
• 避免在用户输入中使用 eval()、new Function()、child_process.exec()。使用带参数数组的 execFile()。

异步与并发

• 优先使用 async/await，而不是回调和原始 Promise .then() 链。
• 始终对 Promise 使用 await——除非明确处理错误，否则绝不启动后便不再等待。
• 可以接受部分失败时使用 Promise.allSettled()；无法接受时使用 Promise.all()。
• 处理 unhandledRejection 和 uncaughtException 事件；记录日志并正常退出。
• 大数据使用流（stream.pipeline）；绝不将整个文件缓冲到内存中。

模块系统

• 新项目使用 ESM（"type": "module"）。避免混用 CJS 和 ESM。
• 只导入所需内容；避免使用 import * from。
• 通过 tsconfig.json 的 paths 和打包工具解析器配置路径别名（@/ → src/）。

TypeScript（强烈推荐）

• 在 tsconfig.json 中使用 "strict": true。没有正当理由时不要使用 any。
• 为所有公共函数定义明确的返回类型。
• 对外部数据使用 unknown，而不是 any；使用类型守卫缩小类型范围。
• 使用 satisfies 运算符验证对象结构，同时避免类型扩大。

依赖管理

• 在 CI 中锁定精确版本（npm ci）。
• 使用 .npmrc 设置 save-exact=true。
• 在 monorepo 中优先使用 pnpm（严格隔离，节省磁盘空间）。
• 定期移除未使用的依赖项。使用 depcheck。

Next.js

基线版本：Next.js 15.2.3+（修复了 CVE-2025-29927）。所有新项目均使用 App Router。

架构

• 默认优先使用 React Server Components（RSC）；仅在需要浏览器 API、事件处理程序或 React 状态时添加 'use client'。
• 保持 Server Components 精简——它们会在每次请求时运行（除非已缓存）。复杂逻辑应放在服务中。
• 使用 Server Actions 处理表单变更。在进行任何数据库操作前，先在服务端使用 Zod 验证。
• 将路由段放在一起：app/(auth)/login/page.tsx、app/api/v1/users/route.ts。

安全

• 绝不要只依赖 Middleware 进行身份验证（CVE-2025-29927 的教训）。在每个 Route Handler、Server Action 和 Data Access Layer（DAL）中重新验证身份。
• 实现 DAL：使用单一模块负责所有数据库访问，并在其中执行身份验证检查。
• 使用 HttpOnly; Secure; SameSite=Strict Cookie 管理会话。绝不要在 localStorage 中存储令牌。
• 设置会话 maxAge：标准用户为 24h，管理员路由为 15 minutes。权限提升时轮换会话 ID。
• 通过 next.config headers 配置 Content-Security-Policy、X-Frame-Options、X-Content-Type-Options。
• 绝不要使用 dangerouslySetInnerHTML。如确有必要，先使用 DOMPurify 清理内容。
• 在 images.remotePatterns 和 fetch 封装中设置 SSRF 允许列表。
• CSRF：使用内置的 Server Action CSRF 保护；对于旧版表单路由，添加显式令牌。

性能

• 所有图片均使用 next/image：它能处理延迟加载、WebP 转换和尺寸优化。
• 使用 next/font 加载字体：可自托管，且不会产生布局偏移。
• 利用 Partial Pre-rendering（PPR）（Next.js 15）：通过 Suspense 实现静态外壳 + 动态占位区。
• 仅在确有需要时，才为开销较大的 Server Components 设置 export const dynamic = 'force-dynamic'。
• 使用 unstable_cache / revalidateTag 实现精细的缓存失效。
• 在 CI 流水线中使用 Lighthouse CI + Core Web Vitals 进行测量。
• 尽量缩小客户端包：对较大的客户端组件使用 import dynamic from 'next/dynamic'。

数据获取

• 尽可能在 Server Components 中获取数据——无需 API 往返，可直接访问数据库或服务。
• 使用 React cache() 在单次渲染过程中对请求去重。
• 对于客户端数据，使用 React Query / SWR，并采用恰当的 stale-while-revalidate 策略。

错误处理

• 在每个路由段边界实现 error.tsx，以便隔离错误并进行恢复。
• 实现 not-found.tsx 处理 404。
• 绝不要向客户端暴露堆栈跟踪或内部路径。

---

NestJS

基线版本：NestJS 11+、Node.js 22 LTS。

架构

• 遵循 模块化架构：每个领域对应一个模块（UserModule、AuthModule、PaymentModule）。
• 保持 Controller 精简：验证输入、委托给 Services，并返回 HTTP 响应。
• Services 包含业务逻辑；Repositories/DAOs 负责数据访问。
• 使用 DTO，结合 class-validator、class-transformer 和全局 ValidationPipe（{ whitelist: true, forbidNonWhitelisted: true }）。
• 使用 Guards 进行身份验证和授权；使用 Interceptors 处理横切关注点（日志记录、转换）；使用 Filters 映射错误。

安全

• 全局应用 ThrottlerGuard。针对敏感端点（身份验证、密码重置）按路由覆盖设置。
• 使用 @nestjs/passport + passport-jwt。通过 JwtAuthGuard 在每个受保护路由上验证 JWT。
• 绝不要在代码中存储敏感配置。使用 @nestjs/config，并通过 Joi 验证环境变量模式。
• 在 main.ts 中通过 app.use(helmet()) 应用 Helmet。
• 显式启用 CORS：app.enableCors({ origin: allowlist, credentials: true })。
• 对超出简单角色检查范围的细粒度权限检查，使用 casl 或自定义 RBAC Guard。

性能

• 在高吞吐量场景中，使用 Fastify 适配器（@nestjs/platform-fastify），而非 Express。
• 使用 ClassSerializerInterceptor + Exclude() 序列化响应，防止数据泄露。
• 对读取密集型且开销较大的端点，使用搭配 Redis 的 CacheInterceptor。
• 使用 NestJS 队列（@nestjs/bull 或 @nestjs/bullmq）进行异步后台处理。
• 所有服务/存储库方法都使用 async。绝不使用同步文件 I/O。

测试

• 使用 Jest 模拟对象隔离测试服务和守卫。
• 使用 @nestjs/testing 的 Test.createTestingModule() 对模块进行集成测试。
• 使用 supertest 对完整应用进行端到端测试。

---

Java

基线：最低要求为 Java 21 LTS。新项目使用 Java 25 LTS（于 2025 年 9 月发布）。

现代语言特性

• 使用 Records 作为不可变数据载体，取代冗长的 POJO。
• 使用 Sealed Classes + Pattern Matching（switch 表达式）实现穷尽式类型层级。
• 使用 Text Blocks 编写多行字符串（SQL、JSON、HTML）。绝不拼接 SQL 字符串。
• 在上下文中类型显而易见时，使用 var 进行局部类型推断。
• 正确使用 Optional<T>：仅将其用作可空值的返回类型，不要用于字段或参数。
• 优先使用不可变集合：List.of()、Map.of()、Set.of()。

并发 — 虚拟线程（Java 21+）

• 对 I/O 密集型工作使用 虚拟线程（Thread.ofVirtual()）。虚拟线程很轻量，可同时存在数百万个。
• 不要将虚拟线程放入线程池——每个任务都创建一个新线程。使用 Executors.newVirtualThreadPerTaskExecutor()。
• Java 24+：虚拟线程不再会因 synchronized 而被固定（JEP 491）。但仍应避免长时间运行的 synchronized 块。
• 使用 结构化并发（StructuredTaskScope，在 Java 25 中为预览功能）管理分叉子任务的生命周期。
• 使用 作用域值（Java 21+）代替 ThreadLocal，以便在虚拟线程间传递上下文。
• 平台线程和响应式编程仅用于真正的 CPU 密集型工作负载。

安全

• 使用 PreparedStatement 或 JPA 命名参数——绝不通过拼接字符串构造 SQL。
• 使用 bcrypt 或 argon2（spring-security-crypto）对密码进行哈希。绝不要单独使用 SHA-*。
• 使用 Bean Validation（@Valid、@NotNull、@Size）在边界处验证所有外部输入。
• 使用等效于 SecurityManager 的控制措施：限制不可信代码的反射和文件访问。
• 保持依赖项更新。在 CI 中使用 dependency-check-maven 或 Snyk。
• 不要使用 Java 原生反序列化来反序列化不可信数据。优先使用 JSON/Protobuf。

性能

• 调优 GC：对延迟敏感型服务优先使用 ZGC 或 G1GC；对暂停时间目标一致的场景使用 Shenandoah。
• 使用 类数据共享（CDS） 和 AOT 编译（Project Leyden）加快启动速度。
• 使用连接池：HikariCP（Spring Boot 中的默认选项），并调优 maximumPoolSize。
• 避免不必要的装箱/拆箱。批量处理数值时使用基本类型流（IntStream、LongStream）。
• 优化前使用 async-profiler 进行性能分析。

代码质量

• 始终应用 @Nullable / @NonNull 注解（Spring Boot 4+ 使用 JSpecify）。
• 在 CI 中使用 SpotBugs、Checkstyle 和 PMD 强制执行代码规范。
• 使用 JUnit 5 + AssertJ 编写单元测试。使用 Testcontainers 进行集成测试。
• 控制圈复杂度。提取方法。优先使用组合而非继承。

---

Spring Boot

基线：Spring Boot 4.0（Spring Framework 7，最低要求 Java 17，并针对 Java 25 进行了优化）。尚未升级到 SB4 的项目使用 Spring Boot 3.5。

配置

• 为了提高可读性，使用 application.yml，而非 application.properties。
• 使用 @ConfigurationProperties + @Validated + Bean Validation 注解验证配置。
• 绝不硬编码凭据。使用 Spring Cloud Config、Vault 或环境变量。
• 使用 配置文件（spring.profiles.active）区分环境。绝不要将开发环境配置部署到生产环境。

并发与性能

• 启用虚拟线程：spring.threads.virtual.enabled=true（Spring Boot 3.3+）。
• 使用虚拟线程执行器，通过 @Async 运行后台任务。
• 仅在需要支持背压的响应式流（例如流式传输大型数据集）时使用 Spring WebFlux（Project Reactor）。对于标准 CRUD，虚拟线程 + WebMVC 更简单，性能也同样出色。
• 使用由 Redis 支持的 Spring Cache（@Cacheable、@CacheEvict），缓存开销较大的读取操作。
• 在生产环境中启用 HTTP/2（server.http2.enabled=true）。

安全性（Spring Security 6+）

• 使用 SecurityFilterChain Bean 方式。避免扩展 WebSecurityConfigurerAdapter（已从 Spring Security 6 中移除）。
• 在服务方法中使用 @PreAuthorize("hasRole('...')") 实现方法级安全控制，而不只是控制器层。
• 面向浏览器的应用应启用 CSRF 保护。仅对使用 JWT 的无状态 API 禁用。
• 通过 CorsConfigurationSource Bean 配置 CORS，而不是在每个控制器上使用 @CrossOrigin。
• 使用 Spring 的 PasswordEncoder（BCryptPasswordEncoder 或 Argon2PasswordEncoder）。
• 验证 JWT 的受众（aud）和颁发者（iss）声明。设置较短的过期时间（15–60 分钟），并使用刷新令牌。

数据访问

• 使用 Spring Data JPA，并搭配 QueryDSL 或 Criteria API 编写动态查询。
• 避免在同一个类的公共方法上使用 @Transactional（代理会被绕过）。使用自注入或独立的服务层。
• 设置 spring.jpa.open-in-view=false。在事务外进行延迟加载会导致 LazyInitializationException。
• 使用 Testcontainers 和 @SpringBootTest，针对真实数据库编写集成测试。
• 使用 Flyway 或 Liquibase 管理数据库架构。切勿使用自动 DDL（生产环境中设置 spring.jpa.hibernate.ddl-auto=validate）。

可观测性

• 引入 spring-boot-starter-actuator 和 micrometer-tracing-bridge-otel。
• 将指标导出到 Prometheus；将跟踪数据导出到 Jaeger/Tempo。
• 暴露 /actuator/health、/actuator/metrics、/actuator/prometheus。保护所有其他 Actuator 端点。
• 使用 Logback + logstash-logback-encoder 实现结构化日志记录。

---

Python

基线：Python 3.12+。新项目使用 3.13。全面启用类型检查。

项目结构

src/
  app/
    api/       # FastAPI routers / Django views
    services/  # business logic
    models/    # ORM models
    schemas/   # Pydantic schemas
    core/      # config, security, db
  tests/
pyproject.toml

类型安全

• 为所有函数和类属性添加类型提示（def fn(x: int) -> str）。
• 在 CI 中运行 mypy --strict 或 pyright。合并前确保类型错误为零。
• 使用 TypedDict 定义字典结构；使用 dataclass 或 Pydantic 模型作为数据载体。
• 适用时使用 Protocol 实现结构化类型，而不是使用 ABC。

异步与性能

• 使用 asyncio 搭配 FastAPI 或 Starlette 构建异步 Web 服务。
• 对所有 I/O 密集型函数使用 async def。不要在异步上下文中调用阻塞函数，应使用 asyncio.run_in_executor() 或 anyio.to_thread.run_sync()。
• 在生产环境中使用 uvicorn + gunicorn（多个工作进程）。
• 在异步服务中使用 httpx（异步版），不要使用 requests（同步版）。
• 使用 py-spy 或 austin 分析 CPU 瓶颈；使用 memray 分析内存。
• 在高频使用的类上使用 __slots__，以降低内存开销。

安全性

• 使用 Pydantic v2 模型（BaseModel、model_validator）验证所有输入。它同时提供架构验证和解析功能。
• 使用 passlib 搭配 argon2 或 bcrypt 处理密码。
• 使用 python-jose 或 PyJWT 处理 JWT，并显式指定允许的算法（algorithms=["RS256"]）。
• 对所有 SQL 查询进行参数化。切勿使用 f-string 编写 SQL。
• 在 CI 中使用 bandit 进行静态安全分析。
• 在 requirements.txt 或 pyproject.toml 中固定依赖版本。在 CI 中使用 pip-audit。
• 避免对不可信数据使用 pickle。优先使用 JSON 或 MessagePack。

依赖项与环境管理

• 使用 uv（2024 年起的标准工具）快速解析依赖项并管理虚拟环境。
• 在 pyproject.toml 中定义所有依赖项并指定版本约束。使用 uv lock 锁定依赖项。
• 绝不要在生产服务器上全局安装软件包；始终使用虚拟环境。

测试

• 使用 pytest 和 pytest-asyncio 编写异步测试。
• 使用 hypothesis 对数据转换逻辑进行基于属性的测试。
• 覆盖率达到 ≥80%；安全关键路径必须达到 100%。
• 使用 factory_boy 或 polyfactory 生成测试数据。

---

Elixir

基线：Elixir 1.17+、OTP 27+。

核心原则

• 拥抱 BEAM Actor 模型：进程开销很小（300–2700 字节）。可以大量创建进程。
• 让它崩溃：编写正常执行路径；使用监督器从故障中恢复。
• 优先使用不可变数据。所有值都是不可变的；函数会返回新值。
• 在所有场景中使用模式匹配——函数头、case、with、receive。
• 使用管道（|>）实现可读的数据转换。

并发与 OTP

• 使用 OTP 行为构建：GenServer、GenStateMachine、Supervisor、DynamicSupervisor。
• 有计划地设计监督树：明确哪些进程是关键进程，哪些是临时进程。
• 使用 Task.async/await 并行执行任务并限制并发；批量处理时使用带有 max_concurrency 的 Task.async_stream。
• 使用 Registry 查找进程；使用 pg 管理分布式进程组。
• 避免在单个进程中运行耗时计算——这会阻塞调度器。将其交由工作池（poolboy、nimble_pool）或 Task 处理。
• 使用 GenStage / Broadway 构建支持背压的数据管道。

容错

• 监督策略：独立工作进程使用 :one_for_one；有序依赖使用 :rest_for_one；紧密耦合的进程组使用 :one_for_all。
• 为监督器设置适当的 max_restarts 和 max_seconds。
• 使用 :ets 存储内存中的共享状态（进程崩溃后数据仍会保留）；使用 :persistent_term 存储读操作频繁的全局配置。

性能

• 使用 :fprof、eflambe 或 Erlang 内置的 :erlang.trace 进行性能分析。
• 避免在热点路径中创建大型二进制数据——使用高效的模式匹配处理二进制数据，而非拼接字符串。
• 使用 Stream 对大型集合进行惰性求值；Enum 会立即求值。
• 对于 CPU 密集型 NIF，使用 Rustler（Rust NIF）——它比 C NIF 更安全，也不会有段错误风险。

安全

• 在渲染前清理所有用户输入。使用 Phoenix.HTML.safe_to_string / html_escape。
• 使用 Argon2（argon2_elixir）进行密码哈希。
• 在 config/runtime.exs 中从环境变量读取并存储密钥。绝不要将密钥放在 config.exs 中。
• 使用 guardian 或 joken 处理 JWT，并固定算法。
• 使用 Ecto.Changeset 或 Schematic 验证所有外部数据。

---

Phoenix

基线：Phoenix 1.7+、Ecto 3.11+。

架构

• 遵循 Context 模式：将相关的 schema、changeset 和查询封装在 context 模块中（例如 Accounts、Catalog）。
• 控制器只负责解析参数、调用 context 和渲染响应。控制器中不得包含业务逻辑。
• 使用 changeset 执行所有数据验证和转换——无论是 Web 场景还是程序化场景。
• 分离读写职责：查询函数返回数据；命令函数返回 {:ok, result} 或 {:error, changeset}。

实时功能（Phoenix Channels 与 LiveView）

• 使用 Phoenix LiveView 构建交互式 UI，无需编写自定义 JS（由有状态 WebSocket 支持）。
• 对于不适合 LiveView 的多人游戏或 pub/sub 模式，使用 Phoenix Channels。
• 使用 Phoenix.PubSub + Redis 或 libcluster（用于分布式 Erlang）在多个节点间扩展 PubSub。
• 将 LiveView socket assigns 限制为模板实际渲染的内容——不要在 socket 中存储大型二进制数据。

性能

• 使用 Cowboy 2.x 启用 HTTP/2。
• 处理大型数据集时使用 Ecto 的 Repo.stream（避免将所有记录加载到内存中）。
• 显式使用 preload；切勿依赖隐式延迟加载（Ecto 不支持此功能——你会得到 %Ecto.Association.NotLoaded{}）。
• 在 LiveView 中使用 :cache_store，或使用 ConCache/Cachex 缓存数据和已渲染的片段。
• 使用 telemetry 事件和 Prometheus exporter（prom_ex）收集指标。

安全

• 使用 Phoenix.Token 创建签名的、有过期时间的令牌（用于密码重置、电子邮件确认）。
• 在 Router 中启用 CSRF 保护（plug :protect_from_forgery）。
• 在 Plug.Conn 插件中设置严格的 CSP、X-Frame-Options 和其他安全标头。
• 使用 PlugAttack 或 Hammer 限制速率。
• 验证所有路由参数——切勿将原始 conn.params 传递给 Ecto 函数。
• 使用 Ecto.Changeset 显式允许字段。

---

Erlang

基线：OTP 27+。

核心原则

• 以进程为中心思考。每个进程都有自己的堆、GC 和邮箱——实现真正的隔离。
• 使用 OTP 行为（gen_server、gen_statem、supervisor），而不是直接使用 spawn。
• 编写带超时的防御式接收逻辑，避免邮箱泄漏。
• 在 CI 中使用 dialyzer（基于成功类型的静态分析）——它能发现实际的错误。
• 使用 proper 或 PropEr 进行基于属性的测试。

可靠性

• 采用崩溃隔离设计：某个进程崩溃时不应导致连锁故障。监督者会重启该进程。
• 对需要跨节点实现 ACID 的分布式、内存或磁盘存储，使用 :mnesia。
• 使用发布包（rebar3 release 或 mix release）部署到生产环境——它们独立完整，无需安装运行时。
• 热代码升级：对于不能容忍停机的关键系统，使用 appup 文件。

性能

• 优先使用二进制模式匹配，而不是字符串操作——二进制效率高，字符链表则不然。
• 避免传递大型消息——发送引用或 pid，而不是大型数据结构。
• 调整调度器数量以匹配 CPU 拓扑。使用 :erlang.system_info(:schedulers_online)。
• 使用 ets，让多个进程能够无锁并发访问内存数据。

---

Rust

基线：Rust 1.80+ (stable)。使用 rustup 管理工具链。

所有权与内存安全

• 理解借用检查器——它是正确性的保障，而非障碍。应顺应其规则。
• 在结构体中优先使用自有数据；在可能的情况下，在函数签名中使用借用。
• 在线程间共享所有权时使用 Arc<T>；仅在单线程环境中使用 Rc<T>。
• 使用 Mutex<T> / RwLock<T> 保护共享的可变状态。优先使用消息传递（mpsc、tokio::sync::mpsc），而不是共享状态。
• 避免使用 unsafe 块。确有必要时，应将其隔离、记录不变量，并封装在安全抽象中。
• 对返回 Result 或 Option 的函数使用 #[must_use]。

错误处理

• 所有可能失败的操作都使用 Result<T, E>。生产代码中切勿使用 .unwrap()——应使用 ? 运算符或显式处理。
• 定义领域专用的错误枚举。库 crate 使用 thiserror；应用 crate 使用 anyhow。
• 在传播错误时附加上下文：ctx_err.context("while reading config")。

异步（Tokio）

• 网络服务使用 Tokio 作为异步运行时。仅在特定用例中使用 async_std。
• 使用 tokio::spawn 执行独立的异步任务。使用 JoinSet 管理多个任务。
• 避免在异步上下文中进行阻塞调用：对 CPU 密集型或阻塞式 I/O 使用 tokio::task::spawn_blocking。
• HTTP 服务使用 tower 中间件栈（超时、重试、负载丢弃、速率限制）。
• 使用 axum 或 actix-web 构建 HTTP API。两者都适合生产环境。

性能

• 零成本抽象：迭代器、泛型和 trait 会编译为高效代码。
• 使用 cargo flamegraph 或 perf 进行性能分析。使用 criterion 进行微基准测试。
• 优先使用栈分配。仅在需要堆分配或动态分发时使用 Box。
• 使用 bytes::Bytes 低成本克隆网络缓冲区（引用计数）。
• 在 release 配置中启用 LTO（lto = true）并设置 codegen-units = 1，以实现最大程度的优化。

安全

• 在 CI 中使用 cargo audit 检查依赖项中已知的 CVE。
• 使用 cargo deny 强制执行许可证和重复依赖项策略。
• 使用 cargo +nightly fuzz（基于 libFuzzer）对解析代码进行模糊测试。
• 绝不通过字符串格式化来构造 SQL 或 shell 命令。

---

Go（Golang）

基线：Go 1.23+（使用最新稳定版本：截至 2026 年初为 Go 1.24）。

项目布局

遵循标准 Go 项目布局：

cmd/          # main packages (one per binary)
internal/     # private packages (not importable externally)
pkg/          # public reusable packages
api/          # OpenAPI/proto definitions

• 积极使用 internal/ 来强制封装。

符合 Go 惯用法

• 错误是值。返回 (T, error)。显式检查每个错误——Go 没有异常。
• 使用 errors.Is() 和 errors.As() 检查错误。使用 fmt.Errorf("ctx: %w", err) 包装错误。
• 对所有执行 I/O、RPC 或可能被取消的函数，将 context.Context 作为第一个参数。
• 使用 context 包处理截止时间、取消和请求作用域值。不要使用 goroutine 局部状态。
• 优先使用小接口。最佳接口包含 1–3 个方法。接受接口，返回具体类型。
• 使用 defer 清理资源（关闭、解锁）。始终使用 defer resp.Body.Close()。

并发

• Goroutine 成本低（约 2KB）。可按请求/任务启动。
• 始终为 goroutine 配对完成通道或 sync.WaitGroup，以避免 goroutine 泄漏。
• 使用通道通信；仅在通道不便使用时，才用 sync.Mutex 保护共享状态。
• 使用 errgroup（golang.org/x/sync/errgroup）管理 goroutine 组并传播错误。
• 检测竞态：运行 go test -race 测试。修复所有数据竞态——它们的行为未定义。

性能

• 使用 pprof（net/http/pprof）分析 CPU、内存、goroutine 和互斥锁。
• 使用 sync.Pool 复用分配成本高的对象（字节缓冲区）。
• 为已知容量的切片和映射预分配空间：make([]T, 0, n)、make(map[K]V, n)。
• 使用 strings.Builder 和 bytes.Buffer 累积字符串/字节。
• 使用 go test -bench 进行基准测试。使用 benchstat 比较结果。

安全

• 使用 database/sql 预处理语句处理所有 SQL。优先使用 pgx 或 sqlc，而非原始字符串查询。
• 使用 go-playground/validator 或 go-ozzo-validation 验证输入。
• 使用 crypto/rand 生成随机值，绝不使用 math/rand。
• 使用 golang.org/x/crypto/argon2 或 bcrypt 处理密码。
• 为所有 HTTP 客户端和服务器设置超时（ReadTimeout、WriteTimeout、IdleTimeout）。
• 在 CI 中运行 govulncheck 和 staticcheck。

---

React

基线：React 19。始终搭配 TypeScript 使用。

组件设计

• 单一职责：一个组件只做一件事。组件超过约 150 行时应拆分。
• 优先使用带 hooks 的函数组件。不要使用类组件。
• 优先使用组合，避免深层嵌套的 prop 逐层传递。仅在必要时提升状态。
• 使用复合组件和渲染属性构建灵活、可复用的 UI 基础组件。
• 将组件、样式和测试放在同一目录中。

状态管理

• 本地 UI 状态：useState、useReducer。
• 共享/服务端状态：React Query (TanStack Query) 或 SWR——不要用 Redux 管理远程数据。
• 全局客户端状态：Zustand（轻量）或 Jotai（原子化）——除非有复杂状态机，否则避免使用 Redux。
• 对非紧急状态更新使用 useTransition 和 useDeferredValue（保持 UI 响应灵敏）。

性能

• 谨慎且正确地使用记忆化：对昂贵的计算使用 useMemo，对传递给记忆化子组件的稳定函数引用使用 useCallback，对耗费性能的纯组件使用 React.memo。
• 在列表中正确使用 key 属性——使用稳定的 ID，绝不使用数组索引（会导致协调错误）。
• 使用 Suspense + lazy() 进行代码拆分。至少应在路由边界处拆分。
• 对于频繁重新渲染的组件，避免在 JSX 渲染方法中创建匿名函数。
• 使用 useId() 生成稳定且兼容 SSR 的 ID。
• 优化渲染前，先使用 React DevTools Profiler 进行分析。

无障碍

• 操作使用 <button>，导航使用 <a>。绝不要让 <div> 可点击。
• 所有图片都必须有 alt 属性：内容图片使用描述性文本，装饰性图片使用 alt=""。
• 在模态框打开/关闭和路由转换时，明确管理焦点。
• 对动态内容更新（通知、状态消息）使用 aria-live 区域。
• 使用 useId() 将 <label> 可靠地关联到表单输入项。
• 使用 @testing-library/react 进行测试（通过无障碍角色/标签查询，而不是 DOM 结构）。

安全

• 绝不要将未经净化的数据用于 dangerouslySetInnerHTML。
• 不要在 localStorage 中存储身份验证令牌——请使用 HttpOnly Cookie。
• 避免使用 eval() 或 new Function()。
• 为改善用户体验，可在客户端验证表单数据；但务必在服务端重新验证。

---

Vue

基线：Vue 3.5+，使用 Composition API 和 <script setup>。始终使用 TypeScript。

Composition API

• 所有组件都使用 <script setup>。它更简洁，类型推断也更好。
• 将组合式函数整理在 src/composables/ 中——每个函数都是专注且可复用的响应式逻辑单元。
• 使用带 TypeScript 泛型的 defineProps<{}>() 和 defineEmits<{}>()，确保 props/events 类型安全。
• 使用 defineModel()（Vue 3.4+）实现双向绑定——替代手动组合 emit 和 prop 的模式。

响应性

• 基本类型使用 ref()；对象使用 reactive()（但要注意，解构会导致响应性丢失）。
• 使用 computed() 处理派生状态——它会缓存结果并延迟求值。
• 使用 watchEffect() 自动处理依赖多个响应式数据源的副作用。
• 需要获取新旧值，或控制惰性/立即执行时，使用 watch()。
• 绝不要直接修改 props。 应触发事件或使用 defineModel()。

性能

• 对数据稳定的重复模板使用 v-memo。
• 对无需深层响应性的较大对象，使用 shallowRef() 和 shallowReactive()。
• 对长列表进行虚拟化：使用 vue-virtual-scroller 或 tanstack-virtual。
• 使用 defineAsyncComponent() 延迟加载较重的组件。
• 将 v-if 和 v-for 放在不同的元素上——v-if 的优先级更高，会破坏 v-for 的预期行为。

状态管理

• Pinia 是官方标准。新项目不要使用 Vuex。
• 让 store 专注明确：每个领域实体/功能使用一个 store。
• 使用 storeToRefs() 解构 store 状态，避免丢失响应性。
• 使用 store action 执行异步操作；保持 getter 纯净。

无障碍

• 遵循与 React 无障碍相同的规则。Vue 没有特殊豁免。
• 构建组件库时，使用 v-bind 根据 props 动态展开 ARIA 属性。

---

Nuxt

基线：Nuxt 4（或稳定版 Nuxt 3.15+）。使用 Vue 3 和 Nitro 服务端引擎。

项目结构（Nuxt 4 srcDir: 'app/'）

app/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  stores/
server/
  api/
  middleware/
  routes/
  utils/
public/
nuxt.config.ts

渲染策略

• 按路由选择：仅客户端渲染时使用 definePageMeta({ ssr: false })；默认使用 SSR。
• 在页面中使用 useFetch / useAsyncData，实现兼容 SSR 且支持水合的数据获取。
• 在服务端路由和事件处理程序中直接使用 $fetch（不会产生客户端开销）。
• 避免在 SSR 上下文中混入仅限客户端的代码。使用 <ClientOnly> 包装器或 process.client 守卫。

性能

• 使用 nuxt/image 自动优化图片。
• 使用 nuxt/fonts 托管字体，避免 FOIT。
• 使用 Nitro 启用 ISR（增量静态再生）：routeRules: { '/blog/**': { isr: 60 } }。
• 使用 useNuxtApp().$router 进行程序化导航，不要直接导入 Vue Router。
• 配置 experimental.viewTransition: true，实现流畅的页面过渡。

安全

• 使用 Nuxt Security 模块（nuxt-security）自动设置安全标头、速率限制和 CSRF 防护。
• 切勿将仅限服务端的环境变量暴露给客户端：使用 runtimeConfig.secretKey（仅限服务端），而非 runtimeConfig.public.apiUrl（客户端可安全访问）。
• 使用 Zod 或 H3 的 getValidatedBody 验证所有 server/api/ 输入。
• 对身份验证 Cookie 使用 useCookie，并设置 httpOnly: true, secure: true, sameSite: 'strict'。

服务端路由（Nitro）

• 使用 server/api/ 定义 API 端点。使用 server/middleware/ 定义全局服务端中间件。
• 配合 H3 工具（readBody、getQuery、setHeader）使用 defineEventHandler。
• 在每个处理器中验证输入：const body = await readValidatedBody(event, schema.parse)。
• 使用 Nitro 内置存储（useStorage）作为 KV、缓存和会话后端。

---

Astro

基线：Astro 5+。内容优先，采用 Islands 架构。

核心原则

• 默认不包含 JS。 输出 HTML 和 CSS。仅使用 client:* 指令添加 JS。
• 使用 Astro 构建内容丰富的网站（营销网站、文档、博客）。搭配 React/Vue/Svelte 构建交互式 Islands。
• 服务端优先：大多数逻辑在构建时或服务端运行，而非浏览器中。

Islands 架构

• 谨慎使用 client:load，仅用于首屏可见的交互式组件。
• 非关键 UI 优先使用 client:idle（浏览器空闲后加载）。
• 首屏以下的组件使用 client:visible（滚动到视口中时加载）。
• 对于绝不能进行 SSR 的组件（例如依赖身份验证的 UI），使用 client:only="react"。

内容集合

• 在 src/content/config.ts 中使用 Zod 定义架构，确保内容具备类型安全。
• 使用 getCollection() 和 getEntry()，不要使用原始的 import.meta.glob 获取内容文件。
• 将内容图片与内容放在一起，以便 Astro Image 自动优化。

性能

• 所有图片都使用 astro:assets 中的 <Image>。自动转换为 WebP、调整尺寸并延迟加载。
• 优先使用静态输出（output: 'static'），以最大限度提高 CDN 缓存能力。
• 仅对动态路由使用 output: 'server' 或 output: 'hybrid'。
• 启用 experimental.contentLayer，加快内容处理速度。
• 使用 Astro 服务端适配器（Vercel、Netlify、Node），预渲染由 API 提供数据的页面，并设置重新验证。

安全

• 对服务端渲染的路由，使用 Astro 中间件（src/middleware.ts）进行身份验证。
• 切勿在 Astro 组件中暴露私有环境变量；仅在 server.ts / .server.ts 文件中使用 import.meta.env.SECRET_KEY。
• 在服务端适配器配置或 CDN WAF 中设置安全标头。

---

SQL / NoSQL

通用数据库原则

• 架构迁移：始终使用带版本控制的迁移工具（Flyway、Liquibase、Alembic、Ecto migrations、golang-migrate）。切勿在生产环境中手动执行 DDL。
• 零停机部署时，所有迁移都必须向后兼容（先添加列，再删除旧列；先扩展，再收缩）。
• 使用连接池：PgBouncer（PostgreSQL）、ProxySQL（MySQL/MariaDB）。根据 CPU 和服务类型设置连接池大小。
• 为所有数据库连接设置 statement_timeout 和 lock_timeout，防止长时间运行的查询造成阻塞。
• 对需要审计的数据实施软删除（deleted_at TIMESTAMP）。临时数据可以硬删除。
• 所有时间戳均使用 UTC。存储为 TIMESTAMPTZ（PostgreSQL），或存储为 DATETIME 并显式按 UTC 处理。

PostgreSQL 最佳实践

• 使用 TIMESTAMPTZ，而非 TIMESTAMP。使用 UUID 作为分布式主键。
• 定义外键。默认使用 ON DELETE RESTRICT；仅在明确需要时考虑 CASCADE。
• 为外键列创建索引。定期使用 EXPLAIN (ANALYSE, BUFFERS) 分析查询计划。
• 对常见的筛选查询使用 部分索引：CREATE INDEX ON orders (user_id) WHERE status = 'pending'。
• 使用 覆盖索引（INCLUDE）避免在高频读取路径上访问堆表。
• 对半结构化数据，优先使用 JSONB 而非 JSON（可建立索引，采用二进制解析）。
• 避免在应用程序查询中使用 SELECT *。始终明确选择列。
• 使用 COPY 批量导入数据——速度比逐行执行 INSERT 快 10–100 倍。
• 启用 pg_stat_statements 以识别慢查询。定期运行 VACUUM ANALYSE（或确保已调整 autovacuum）。
• 多租户：租户数量适中且需要强隔离时，使用 每个租户一个 schema；高规模 SaaS 则使用 行级安全（RLS）。

MySQL / MariaDB 最佳实践

• 仅使用 InnoDB 引擎。新建表绝不要使用 MyISAM。
• 全程使用 utf8mb4 字符集和 utf8mb4_unicode_ci 排序规则。
• 自增主键优先使用 BIGINT UNSIGNED。规模扩大后，字段大小很重要。
• 将 innodb_buffer_pool_size 设为专用数据库服务 RAM 的 70–80%。切勿接近容器 RAM 上限。
• 使用 EXPLAIN FORMAT=JSON 分析查询。
• 避免使用存储过程处理复杂业务逻辑——将逻辑保留在应用程序代码中。

MongoDB 最佳实践

• 先设计 schema：根据访问模式对数据建模，而不是遵循关系型规范化。
• 在集合级别使用 验证规则（$jsonSchema）强制执行 schema。
• 始终为查询条件和排序字段创建索引。使用 explain("executionStats") 进行验证。
• 使用 writeConcern: { w: "majority" } 确保持久性。使用 readConcern: "majority" 进行强一致性读取。
• 使用 事务（多文档事务，需要副本集）确保跨文档原子性。
• 使用 Atlas，或在可自托管部署中启用副本集——独立运行的 MongoDB 尚未达到生产就绪状态。
• 切勿在文档中嵌入无界数组。当数组可能无限增长时，请使用引用。
• 谨慎使用 $lookup——这可能说明 schema 设计存在问题。对于高频读取路径，优先使用预先联接的文档。

Redis / Valkey 最佳实践

• 将 Redis（或 Valkey 7+）用作 缓存、会话存储和发布/订阅代理，而非主数据库。
• 始终为缓存键设置 TTL。除非有意为之，否则切勿存储没有过期时间的数据。
• 在生产环境中使用 Redis Cluster 或 Sentinel 实现高可用性。单节点 Redis 不具备容错能力。
• 使用 MULTI/EXEC 事务或 Lua 脚本执行原子性的读取-修改-写入操作。
• 使用不同的键命名空间：{service}:{entity}:{id}（例如 auth:session:uuid）。
• 在生产环境中通过 requirepass 和 TLS 提供保护。仅绑定到内部网络——切勿将 Redis 公开暴露。
• 在生产环境中使用 Valkey 9.0.x（截至 2025 年，9.1 已回退为 RC）。

键值与时序数据库

• DynamoDB：采用单表设计；选择键之前先定义访问模式。
• Cassandra：针对写入密集型时序工作负载进行设计；按查询进行反规范化。
• InfluxDB / TimescaleDB：用于指标/遥测数据。按时间分区。设置数据保留策略。

查询与访问模式

• CRUD 操作使用 ORM/查询构建器；复杂分析和性能关键型查询使用原始 SQL。
• 切勿通过字符串插值生成 SQL。使用参数化查询或 ORM 抽象。
• 使用 EXPLAIN ANALYSE 分析并优化慢查询。完成性能分析后再添加索引——不要过早优化。
• 对静态存储的 PII 和金融数据，应用 数据库级列加密（pgcrypto、MongoDB FLE、MySQL AES 函数）。

---

跨领域检查清单

合并前检查清单（每个 PR）

• 在所有入口点进行输入验证
• 代码或日志中不包含机密信息
• 妥善处理错误并以结构化形式返回（绝不吞掉错误）
• 为业务逻辑编写单元测试，为数据库／外部调用编写集成测试
• 未引入 N+1 查询
• 记录新端点的文档（OpenAPI/AsyncAPI）
• 无障碍性：对于 UI 变更，检查语义化 HTML、ARIA 和键盘导航
• npm audit / cargo audit / pip-audit 检查通过
• 数据库迁移向后兼容
• 不硬编码配置值（使用环境变量）

生产环境部署前检查清单

• 所有端点均强制使用 TLS 1.3
• 所有面向公众的端点均启用速率限制
• 健康检查和就绪检查端点返回正确状态
• 使用结构化日志，且关联 ID 在所有服务之间传递
• 已导出指标（Prometheus/OpenTelemetry）
• 已针对 SLO 消耗速率定义告警
• 已将机密信息轮换为不同于开发／预发布环境的值
• 已配置并调整数据库连接池大小
• 已测试备份和恢复流程
• 已为每项服务编写运行手册

---

许可证

MIT License

Copyright (c) 2026 Patrick Aziken / Upperloft Creations Limited

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

版本 2026.1.0 — 由 Upperloft Creations Limited 于 2026 年 5 月发布。
每季度审查一次；请在 https://github.com/skylarng89/engineering-best-practices-skill/issues 提交问题