backend-engineering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

激活此技能后，首次回复请务必以 🧢 表情开头。

Backend Engineering

后端工程

A senior backend engineer's decision-making framework for building production systems. This skill covers the six pillars of backend engineering - schema design, scalable systems, observability, performance, security, and API design - with an emphasis on when to use each pattern, not just how. Designed for mid-level engineers (3-5 years) who know the basics and need opinionated guidance on trade-offs.

面向生产系统构建的资深后端工程师决策框架。此技能涵盖后端工程的六大支柱——schema 设计、可扩展系统、可观测性、性能、安全和 API 设计——重点在于何时使用每种模式，而非仅讲解如何使用。专为掌握基础知识、需要关于权衡取舍的明确指导的中级工程师（3-5 年经验）设计。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Designs a database schema or plans a migration
Chooses between monolith vs microservices or evaluates scaling strategies
Sets up logging, metrics, tracing, or alerting
Diagnoses a performance issue (slow queries, high latency, memory pressure)
Implements authentication, authorization, or secrets management
Designs a REST, GraphQL, or gRPC API
Needs retry, circuit breaker, or idempotency patterns
Plans data consistency across services (sagas, outbox, eventual consistency)

Do NOT trigger this skill for:

Frontend-only concerns (CSS, React components, browser APIs)
DevOps/infra provisioning (use a Terraform/Docker/K8s skill instead)

当用户有以下需求时触发此技能：

设计数据库 schema 或规划迁移
在单体架构与微服务之间做选择，或评估扩容策略
搭建日志、指标、链路追踪或告警系统
诊断性能问题（慢查询、高延迟、内存压力）
实现身份认证、授权或密钥管理
设计 REST、GraphQL 或 gRPC API
需要重试、断路器或幂等性模式
规划跨服务的数据一致性（saga、outbox、最终一致性）

请勿在以下场景触发此技能：

纯前端相关问题（CSS、React 组件、浏览器 API）
DevOps/基础设施部署（请使用 Terraform/Docker/K8s 相关技能）

Key principles

核心原则

Design for failure, not just success - Every network call can fail. Every disk can fill. Every dependency can go down. The question is not "will it fail" but "how does it degrade?" Design graceful degradation paths before writing the happy path.
Observe before you optimize - Never guess where the bottleneck is. Instrument first, measure second, optimize third. A 10ms query called 1000 times matters more than a 500ms query called once.
Simple until proven otherwise - Start with a monolith, a single database, and synchronous calls. Add complexity (microservices, queues, caches) only when you have evidence the simple approach fails. Every architectural boundary is a new failure mode.
Secure by default, not by afterthought - Auth, input validation, and encryption are not features to add later. They are constraints to build within from day one. Use established libraries. Never roll your own crypto.
APIs are contracts, not implementation details - Once published, an API is a promise. Design from the consumer's perspective inward. Version explicitly. Break nothing silently.

为故障设计，而非仅为成功设计——每个网络调用都可能失败，每个磁盘都可能被占满，每个依赖都可能宕机。问题不在于“是否会失败”，而在于“故障时如何降级”。在编写正常流程之前，先设计优雅的降级路径。
先观测再优化——永远不要猜测瓶颈所在。先埋点，再测量，最后优化。一个耗时10ms但被调用1000次的查询，比耗时500ms但仅调用一次的查询影响更大。
保持简单，除非有证据表明需要复杂方案——从单体架构、单一数据库和同步调用开始。只有当简单方案被证明无法满足需求时，再引入复杂性（微服务、队列、缓存）。每个架构边界都是一个新的故障点。
默认安全，而非事后补救——身份认证、输入验证和加密不是后续添加的功能，而是从第一天起就需要遵循的约束。使用成熟的库，永远不要自行实现加密逻辑。
API 是契约，而非实现细节——一旦发布，API 就是一个承诺。从消费者的需求出发向内设计。明确版本号，永远不要静默地破坏现有功能。

Core concepts

核心概念

Backend engineering is the discipline of building reliable, performant, and secure server-side systems. The six pillars form a hierarchy:

Schema design is the foundation - get the data model wrong and everything built on top inherits that debt. Scalable systems define how components communicate and grow. Observability gives you eyes into what's actually happening in production. Performance is the art of making it fast after you've made it correct. Security is the set of constraints that keep the system trustworthy. API design is the surface area through which consumers interact with all of the above.

These pillars are not independent. A bad schema creates performance problems. Poor observability makes security incidents invisible. A poorly designed API forces clients into patterns that break your scaling strategy. Think of them as a connected system, not a checklist.

后端工程是构建可靠、高性能、安全的服务器端系统的学科。六大支柱构成一个层级体系：

Schema 设计是基础——如果数据模型出错，基于它构建的所有内容都会继承技术债务。可扩展系统定义组件如何通信和扩展。可观测性让你能洞察生产环境中实际发生的情况。性能是在确保功能正确之后，让系统变快的艺术。安全是保持系统可信的一系列约束。API 设计是消费者与上述所有部分交互的入口。

这些支柱并非独立存在。糟糕的 schema 会导致性能问题，不足的可观测性会让安全事件隐身，设计不佳的 API 会迫使客户端采用破坏扩容策略的模式。要将它们视为一个相互关联的系统，而非一个检查清单。

Common tasks

常见任务

Design a database schema

设计数据库 Schema

Start from access patterns, not entity relationships. Ask: "What queries will this serve?" before drawing a single table.

Decision framework:

Read-heavy, predictable queries -> Normalize (3NF), add targeted indexes
Write-heavy, high throughput -> Consider denormalization, append-only tables
Complex relationships with traversals -> Consider a graph model
Unstructured/evolving data -> Document store (but think twice)

Indexing rule of thumb: Index columns that appear in WHERE, JOIN, and ORDER BY. A composite index on

(a, b, c)

serves queries on

(a)

(a, b)

, and

(a, b, c)

but NOT

(b, c)

. Check the references/ file for detailed indexing strategies.

Always plan migration rollbacks. A deploy that adds a column is safe. A deploy that drops a column is a one-way door. Use expand-contract migrations for breaking changes.

从访问模式入手，而非实体关系。在绘制任何表之前，先问：“这个 schema 要支持哪些查询？”

决策框架：

读密集、查询可预测 -> 规范化（3NF），添加针对性索引
写密集、高吞吐量 -> 考虑反规范化、追加式表
需要复杂关系遍历 -> 考虑图模型
非结构化/不断演化的数据 -> 文档型数据库（但需谨慎）

索引经验法则： 为 WHERE、JOIN 和 ORDER BY 子句中的列创建索引。

(a, b, c)

上的复合索引支持

(a)

、

(a, b)

和

(a, b, c)

的查询，但不支持

(b, c)

的查询。查看 references/ 文件夹获取详细的索引策略。

始终要规划迁移回滚方案。添加列的部署是安全的，但删除列的部署是一条单行道。对于破坏性变更，使用 expand-contract 迁移模式。

Choose a scaling strategy

选择扩容策略

Is a single server sufficient?
  YES -> Stay there. Optimize vertically first.
  NO  -> Is the bottleneck compute or data?
    COMPUTE -> Horizontal scale with stateless services + load balancer
    DATA    -> Is it read-heavy or write-heavy?
      READ  -> Add read replicas, then caching layer
      WRITE -> Partition/shard the database

Only introduce microservices when you have: (a) independent deployment needs, (b) different scaling profiles per component, or (c) team boundaries that demand it.

Never split a monolith along technical layers (API service, data service). Split along business domains (orders, payments, inventory).

单服务器是否足够？
  是 -> 保持现状。优先垂直扩容。
  否 -> 瓶颈在计算还是数据？
    计算 -> 无状态服务 + 负载均衡 进行水平扩容
    数据 -> 是读密集还是写密集？
      读 -> 添加只读副本，然后引入缓存层
      写 -> 对数据库进行分区/分片

只有在满足以下条件时才引入微服务：(a) 有独立部署需求，(b) 各组件有不同的扩容配置，或 (c) 团队边界要求拆分。

永远不要沿着技术层拆分单体架构（如 API 服务、数据服务）。要沿着业务域拆分（如订单、支付、库存）。

Set up observability

搭建可观测性系统

Implement the three pillars with correlation:

Pillar	What it answers	Tool examples
Logs	What happened?	Structured JSON logs with correlation IDs
Metrics	How is the system performing?	RED metrics (Rate, Errors, Duration)
Traces	Where did time go?	Distributed traces across service boundaries

Define SLOs before writing alerts. An SLO like "99.9% of requests complete in <200ms" gives you an error budget. Alert when the burn rate threatens the budget, not on every spike.

实现具有关联能力的三大支柱：

支柱	解决的问题	工具示例
Logs（日志）	发生了什么？	带关联 ID 的结构化 JSON 日志
Metrics（指标）	系统性能如何？	RED 指标（Rate 速率、Errors 错误数、Duration 耗时）
Traces（链路追踪）	时间消耗在哪里？	跨服务边界的分布式链路追踪

在配置告警之前先定义 SLO。例如“99.9% 的请求在 <200ms 内完成”这样的 SLO 会给你一个错误预算。当消耗速率威胁到错误预算时再触发告警，而不是在每次出现峰值时都告警。

Diagnose a performance issue

诊断性能问题

Follow this checklist in order:

Check metrics - is it CPU, memory, I/O, or network?
Check slow query logs - are there N+1 patterns or full table scans?
Check connection pools - are connections exhausted or leaking?
Check external dependencies - is a downstream service slow?
Profile the code - only after ruling out infrastructure causes

The fix for "the database is slow" is almost never "add more database." It's usually: add an index, fix an N+1, or cache a hot read path.

按以下顺序执行检查清单：

检查指标 - 瓶颈是 CPU、内存、I/O 还是网络？
检查慢查询日志 - 是否存在 N+1 查询模式或全表扫描？
检查连接池 - 连接是否耗尽或泄漏？
检查外部依赖 - 下游服务是否变慢？
分析代码 - 只有在排除基础设施原因后再进行

“数据库变慢”的解决方案几乎从来不是“增加更多数据库”。通常的解决方法是：添加索引、修复 N+1 查询，或缓存热点读路径。

Secure a service

服务安全加固

Minimum security checklist for any backend service:

Authentication: Use OAuth 2.0 / OIDC for user-facing, API keys + HMAC for service-to-service. Never store plain-text passwords (bcrypt/argon2 minimum).
Authorization: Implement at the middleware level. Default deny. Check permissions on every request, not just at the edge.
Input validation: Validate at system boundaries. Use allowlists, not blocklists. Parameterize all SQL queries.
Secrets: Use a secrets manager (Vault, AWS Secrets Manager). Never commit secrets to git. Rotate regularly.
Transport: TLS everywhere. No exceptions.

任何后端服务的最低安全检查清单：

身份认证：面向用户的服务使用 OAuth 2.0 / OIDC，服务间调用使用 API 密钥 + HMAC。永远不要存储明文密码（最低要求使用 bcrypt/argon2）。
授权：在中间件层实现。默认拒绝所有请求，对每个请求都检查权限，而不仅仅在边缘节点检查。
输入验证：在系统边界进行验证。使用白名单，而非黑名单。所有 SQL 查询都要使用参数化查询。
密钥管理：使用密钥管理器（Vault、AWS Secrets Manager）。永远不要将密钥提交到 git。定期轮换密钥。
传输安全：全程使用 TLS，无例外。

Design an API

设计 API

REST decision table:

Need	Pattern
Simple CRUD	REST with standard HTTP verbs
Complex queries with flexible fields	GraphQL
High-performance internal service calls	gRPC
Real-time bidirectional	WebSockets
Event notification to external consumers	Webhooks

Pagination: Use cursor-based for large/changing datasets, offset-based only for small/static datasets. Always include a

next_cursor

field.

Versioning: URL path versioning (

/v1/

) for public APIs, header versioning for internal. Never break existing consumers silently.

Rate limiting: Token bucket for user-facing, fixed window for internal. Always return

Retry-After

headers with 429 responses.

API 选型决策表：

需求	模式
简单 CRUD 操作	标准 HTTP 动词的 REST
灵活字段的复杂查询	GraphQL
高性能内部服务调用	gRPC
实时双向通信	WebSockets
向外部消费者推送事件通知	Webhooks

分页：对于大型/动态数据集使用基于游标（cursor-based）的分页，仅在小型/静态数据集使用基于偏移量（offset-based）的分页。始终返回

next_cursor

字段。

版本控制：公开 API 使用 URL 路径版本化（

/v1/

），内部 API 使用请求头版本化。永远不要静默地破坏现有消费者的功能。

限流：面向用户的服务使用令牌桶算法，内部服务使用固定窗口算法。返回 429 响应时始终附带

Retry-After

响应头。

Handle partial failures

处理部分故障

When services depend on other services, failures cascade. Use these patterns:

Retry with exponential backoff + jitter - for transient failures (network blips, 503s). Cap at 3-5 retries.
Circuit breaker - stop calling a failing dependency. States: closed (normal) -> open (failing, fast-fail) -> half-open (testing recovery).
Idempotency keys - make retries safe. Every mutating operation should accept an idempotency key so duplicate requests produce the same result.
Timeouts - always set them. A missing timeout is an unbounded resource leak.

当服务依赖其他服务时，故障会级联扩散。使用以下模式：

指数退避 + 抖动重试 - 适用于瞬时故障（网络波动、503 错误）。重试次数限制在 3-5 次。
断路器 - 停止调用故障依赖。状态：关闭（正常）-> 打开（故障，快速失败）-> 半开（测试恢复）。
幂等性密钥 - 让重试操作安全。每个写操作都应接受一个幂等性密钥，确保重复请求产生相同结果。
超时设置 - 始终设置超时。缺失超时设置等同于无限制的资源泄漏。

Plan data consistency

规划数据一致性

For distributed data across services:

Strong consistency needed? -> Single database, ACID transactions
Can tolerate eventual consistency? -> Event-driven with outbox pattern
Multi-step business process? -> Saga pattern (prefer choreography over orchestration for simple flows, orchestration for complex ones)

The outbox pattern: write the event to a local "outbox" table in the same transaction as the data change. A separate process publishes outbox events to the message broker. This guarantees at-least-once delivery without 2PC.

对于跨服务的分布式数据：

需要强一致性？ -> 单一数据库，ACID 事务
可容忍最终一致性？ -> 基于事件驱动的 outbox 模式
多步骤业务流程？ -> Saga 模式（简单流程优先使用 choreography（编排），复杂流程使用 orchestration（协调））

Outbox 模式：在与数据变更相同的事务中，将事件写入本地“outbox”表。一个独立的进程将 outbox 事件发布到消息队列。这保证了至少一次投递，无需使用 2PC（两阶段提交）。

Anti-patterns / common mistakes

反模式/常见误区

Mistake	Why it's wrong	What to do instead
Premature microservices	Creates distributed monolith, adds network failure modes	Start monolith, extract services when domain boundaries are proven
Missing indexes on query columns	Full table scans under load, cascading timeouts	Profile queries with EXPLAIN, add indexes for WHERE/JOIN/ORDER BY
Logging everything, alerting on nothing	Alert fatigue, real incidents get buried	Structured logs with levels, SLO-based alerting on burn rate
N+1 queries in loops	Linear query growth per record, kills DB under load	Batch fetches, eager loading, or dataloader pattern
Rolling your own auth/crypto	Subtle security bugs that go unnoticed for months	Use battle-tested libraries (bcrypt, passport, OIDC providers)
Designing APIs from the database out	Leaks internal structure, painful to evolve	Design from consumer needs inward, then map to storage
Destructive migrations without rollback	One-way door that can cause downtime	Expand-contract pattern, backward-compatible migrations
Caching without invalidation strategy	Stale data, cache-database drift, inconsistency	Define TTL, invalidation triggers, and cache-aside pattern upfront

误区	错误原因	正确做法
过早拆分微服务	形成分布式单体，增加网络故障点	从单体架构开始，当业务域边界明确后再拆分服务
查询列未加索引	高负载下出现全表扫描，导致级联超时	使用 EXPLAIN 分析查询，为 WHERE/JOIN/ORDER BY 列添加索引
记录所有日志但不设置有效告警	告警疲劳，真正的事件被淹没	带日志级别的结构化日志，基于 SLO 错误预算消耗速率的告警
循环中的 N+1 查询	查询数量随记录数线性增长，拖垮数据库	批量查询、预加载或使用 dataloader 模式
自行实现认证/加密逻辑	存在不易察觉的安全漏洞，可能数月后才被发现	使用经过实战检验的库（bcrypt、passport、OIDC 提供商）
从数据库向外设计 API	暴露内部结构，难以演进	从消费者需求向内设计，再映射到存储层
无回滚方案的破坏性迁移	单行道，可能导致停机	使用 expand-contract 模式，向后兼容的迁移方案
无失效策略的缓存	数据过期、缓存与数据库不一致	提前定义 TTL、失效触发条件和 cache-aside 模式

References

参考资料

For detailed patterns and implementation guidance on specific domains, read the relevant file from the

references/

folder:

```
references/schema-design.md
```
- normalization, indexing strategies, migration patterns
```
references/scalable-systems.md
```
- distributed patterns, caching, queues, load balancing
```
references/observability.md
```
- logging, metrics, tracing, SLOs, alerting setup
```
references/performance.md
```
- profiling, query optimization, connection pooling, async
```
references/security.md
```
- auth flows, encryption, OWASP top 10, secrets management
```
references/api-design.md
```
- REST/GraphQL/gRPC conventions, versioning, pagination
```
references/failure-patterns.md
```
- circuit breakers, retries, idempotency, sagas

Only load a references file if the current task requires it - they are long and will consume context.

如需特定领域的详细模式和实现指导，请阅读

references/

文件夹中的相关文件：

```
references/schema-design.md
```
- 规范化、索引策略、迁移模式
```
references/scalable-systems.md
```
- 分布式模式、缓存、队列、负载均衡
```
references/observability.md
```
- 日志、指标、链路追踪、SLO、告警配置
```
references/performance.md
```
- 性能分析、查询优化、连接池、异步处理
```
references/security.md
```
- 认证流程、加密、OWASP 十大风险、密钥管理
```
references/api-design.md
```
- REST/GraphQL/gRPC 规范、版本控制、分页
```
references/failure-patterns.md
```
- 断路器、重试、幂等性、saga 模式

仅在当前任务需要时加载参考文件——这些文件篇幅较长，会占用上下文资源。