后端决策逻辑

这份规则描述的是在处理后端相关任务时的核心决策逻辑。后端系统的核心问题是：如何在保证数据正确性和系统稳定性的前提下，高效地处理来自外部的请求并管理系统状态。这套规则涵盖 API 设计、数据建模、业务逻辑组织、安全策略和可观测性，每一部分都是后端工程质量的关键支柱。

一、API 设计的第一性原理

1.1 API 是契约，不是实现

API 一旦发布并有调用方依赖，修改它的成本非常高。调用方需要感知到变化并做出相应调整，这需要协调和时间。因此 API 的设计必须在实现之前经过充分思考，而不是先快速实现一个版本再迭代优化。

设计阶段需要回答的问题：这个 API 解决的是什么问题，调用方需要的最小信息集合是什么，这个 API 的边界在哪里（它不应该做什么），以及这个 API 在未来可能的扩展方向是什么。

1.2 一致性是 API 最重要的特征

调用方在学会一个端点的使用方式之后，应该能够对其他端点有准确的预期。一致性体现在：端点命名的模式（动词还是名词，复数还是单数）、请求参数的位置和格式（path 参数 vs query 参数 vs 请求体）、响应结构（成功时的数据格式、失败时的错误格式）、HTTP 状态码的使用方式（200、201、400、401、403、404、500 各自代表什么）。

1.3 向后兼容优先于完美设计

在需要修改已发布 API 时，优先选择向后兼容的修改方式：添加新的可选字段（调用方忽略它），新增端点（旧端点继续工作），扩展枚举值范围（调用方遇到未知值时优雅降级）。

必须做破坏性修改时，使用版本控制：在 URL 路径或请求头中标注版本，维护旧版本一段时间并给调用方足够的迁移时间，在下线旧版本前发出充分的提前通知。

flowchart TD
    A[需要修改已发布的 API] --> B{是否是破坏性修改}
    B -- 否，可向后兼容 --> C[直接添加新字段或新端点]
    B -- 是，破坏性修改 --> D[评估修改的必要性]
    D --> E[发布新版本 API]
    E --> F[通知调用方迁移]
    F --> G[维护旧版本一段时间]
    G --> H[在约定时间后下线旧版本]
    C --> I[通知调用方新能力可用]

1.4 错误响应的完整性

错误响应和成功响应一样重要。一个好的错误响应包含：机器可读的错误码（让调用方能够区分不同类型的错误并做出不同的处理）、人类可读的错误描述（让开发者能够快速理解出了什么问题）、以及在适当时候包含字段级别的验证错误（让调用方能够将错误定位到具体的输入字段）。

二、数据库设计的核心思维

2.1 数据模型是最难修复的错误

代码可以重写，但数据模型的变更需要同时迁移存量数据，在生产环境中这是有风险的操作。因此数据模型的设计需要比代码设计更谨慎，需要在实现之前充分考虑查询模式、数据关系和未来的扩展方向。

设计数据模型时需要同时考虑：这些数据如何被写入，最常见的查询模式是什么，数据之间的关系是什么，哪些字段会随时间演变，以及历史数据的保留需求。

2.2 范式化与反范式化的权衡

完全范式化减少冗余，保证数据一致性，但查询需要多表连接，在高频查询场景下性能差。反范式化（冗余存储某些字段）提升查询性能，但增加了数据一致性维护的复杂度——每次更新源数据时，所有冗余副本也需要同步更新。

选择依据：基于实际的查询模式，而不是理论上的完美。如果一个查询需要连接五张表，值得考虑在某个地方做适度的反范式化来减少连接操作。

flowchart TD
    A[设计数据模型] --> B[识别核心实体和它们的关系]
    B --> C[分析最常见的查询模式]
    C --> D{查询是否需要大量连接操作}
    D -- 否，连接操作合理 --> E[使用范式化设计\n保证一致性]
    D -- 是，性能不可接受 --> F[识别可以反范式化的部分]
    F --> G[冗余存储高频查询所需的字段]
    G --> H[设计数据同步策略\n确保冗余数据的一致性]
    E --> I[设计索引覆盖高频查询]
    H --> I

2.3 索引设计原则

索引不是越多越好。每个写操作都需要更新所有相关索引，过多的索引会严重降低写性能，也会占用大量存储空间。

索引应该基于实际的查询模式来设计：分析哪些查询是高频的，这些查询的过滤条件是什么，排序字段是什么，然后设计能够覆盖这些查询的索引。

一个好的索引设计能够让查询直接从索引中获取所需数据（覆盖索引），而不需要回表查询原始记录。

2.4 软删除的使用规则

在大多数业务系统中，软删除（标记删除时间戳而不是真正删除记录）是更安全的选择：它保留了审计历史，支持数据恢复，允许实现"回收站"功能。

软删除的代价是：所有查询都需要加入过滤条件来排除已删除的记录，如果遗漏了这个条件，已删除的数据就会出现在结果中。解决这个问题的方式是在数据访问层统一封装这个过滤条件，而不是让每个查询自己加。

三、业务逻辑的组织原则

3.1 业务逻辑必须集中

业务逻辑分散在 API 处理器、数据库查询和工具函数中，是最难维护的代码结构之一。当一个业务规则需要修改时，需要找到所有包含这个规则的地方并同步修改，很容易遗漏。

业务逻辑应该集中在服务层或领域模型中。任何渠道（API 请求、后台任务、定时任务、消息消费）调用同一个业务操作时，都经过同一段业务逻辑，确保业务规则被统一执行。

flowchart TD
    subgraph 调用渠道
        A1[REST API 请求]
        A2[GraphQL 请求]
        A3[后台定时任务]
        A4[消息队列消费]
    end
    subgraph 业务逻辑层
        B[统一的业务服务\n包含所有业务规则\n状态机\n验证逻辑]
    end
    subgraph 数据层
        C[数据库]
        D[缓存]
        E[外部服务]
    end
    A1 & A2 & A3 & A4 --> B
    B --> C & D & E

3.2 状态机的显式建模

如果一个实体有多个状态，以及在状态之间转换的规则，这个状态机应该被显式建模，而不是散落在各处的 if-else 判断。

显式建模的好处：状态转换的合法性可以被统一验证（不允许从"已完成"状态转换回"处理中"状态）；状态转换可以触发副作用（状态变为"已支付"时发送邮件通知）；整个状态机的全貌在一个地方可见，而不是需要阅读所有代码才能理解。

3.3 事务边界的明确定义

涉及多个数据操作的业务逻辑需要明确定义事务边界：哪些操作需要在同一个事务中完成（要么全部成功，要么全部失败），哪些操作可以独立执行。

跨服务的操作无法使用数据库事务，需要使用补偿事务模式（Saga 模式）：每个操作都有对应的补偿操作，当某个步骤失败时，依次执行之前已成功步骤的补偿操作来回滚效果。

四、认证与授权的实施规则

4.1 认证在授权之前

每个需要保护的 API 端点都需要先验证调用方的身份（认证），再验证这个身份是否有权限执行请求的操作（授权）。这两个步骤都不能省略。

认证失败返回 401（未认证），授权失败返回 403（无权限）。区分这两个错误对调用方处理逻辑很重要：401 意味着需要重新登录，403 意味着当前用户没有权限执行这个操作（重新登录也没用）。

4.2 最小权限原则的实施

每个用户、每个服务账号、每个 API 密钥都只应该拥有完成其工作所必需的最小权限集合。

实施这个原则意味着：不应该有一个拥有所有权限的"超级用户"被大量系统使用；数据库的服务账号只有查询和写入权限，没有删除表或修改结构的权限；第三方集成使用专门创建的、权限受限的 API 密钥。

4.3 密钥和敏感配置的管理

任何形式的密钥（数据库密码、API 密钥、JWT 签名密钥、第三方服务凭证）都不应该出现在代码库中，不应该出现在版本控制的历史记录里，不应该出现在日志中。

密钥通过环境变量或专用的密钥管理服务注入到运行时。在不同的环境（开发、测试、生产）使用不同的密钥，生产环境的密钥只有生产系统可以访问。

五、性能与可观测性

5.1 缓存策略的决策框架

缓存是解决性能问题的有效手段，但引入缓存同时引入了数据一致性的复杂性。不是所有数据都适合缓存。

适合缓存的数据特征：读取频率高、更新频率低、计算成本高、对短暂的过期数据可以接受。

flowchart TD
    A[考虑为某个数据引入缓存] --> B{读取频率是否足够高}
    B -- 否 --> C[不需要缓存\n缓存带来的复杂性不值得]
    B -- 是 --> D{更新频率如何}
    D -- 极高，几乎实时变化 --> E[缓存效果差\n考虑其他优化手段]
    D -- 中等或低 --> F{对数据过期的容忍度}
    F -- 不能接受过期数据 --> G[主动失效策略\n更新时立即清除缓存]
    F -- 可以接受短暂过期 --> H[TTL 策略\n设置合理的过期时间]
    G & H --> I[实现缓存并监控命中率]

5.2 日志质量标准

日志的目的是在系统出现问题时帮助快速定位根因。一条有价值的日志包含：发生了什么（操作的描述）、在哪里发生（服务名、文件名、函数名）、何时发生（精确的时间戳）、谁触发的（用户 ID 或请求 ID）、结果如何（成功或失败，失败时的错误详情）。

结构化日志（JSON 格式）优于非结构化日志（纯文本），因为结构化日志可以被日志系统索引和查询，可以基于任意字段过滤，可以方便地与链路追踪系统集成。

不应该记录的内容：密码、token、信用卡号、身份证号、医疗信息等敏感数据永远不应该出现在日志中。

5.3 关键指标的监控

可观测性的目标是能够在问题发生时快速回答：系统的哪个部分出了问题，问题的影响范围是什么，问题是什么时候开始的。

需要监控的关键指标类别：请求量（判断流量是否正常）、错误率（判断系统是否在正常工作）、延迟（判断系统的响应速度是否可接受）、资源使用（判断是否接近资源上限）。

这四类指标能够覆盖大多数系统问题的早期发现，是监控系统的最小有效集合。