architecture-paradigm-client-server

客户端-服务端与点对点范式

何时采用此范式

• 用于具有集中式服务的传统应用，例如与后端 API 通信的 Web 或移动客户端。
• 用于探索去中心化或“离线优先”能力、并依赖点对点同步的系统。
• 用于正式记录信任边界、客户端-服务端版本协商和 API 演进策略。

何时不应使用

• UI 与逻辑之间没有网络边界的系统（使用 archetypes:architecture-paradigm-modular-monolith）
• 首次在不同范式之间进行选择（使用 archetypes:architecture-paradigms）

采用步骤

1. 明确职责：清晰划分客户端与服务端各自承载的逻辑和数据，目标是尽量减少重复。
2. 记录契约：正式记录所有 API、数据架构、身份验证流程，以及处理不同客户端版本所需的任何能力协商。
3. 规划版本偏差：制定管理不同客户端和服务端版本的策略，例如使用功能标志、用于内容协商的 Accept 标头，或为 API 使用语义化版本控制。
4. 处理连接问题：如果应用并非纯粹的客户端-服务端架构，则应针对间歇性连接进行设计。这可能包括实现离线缓存、数据同步协议，或对等发现和成员管理服务。
5. 保护所有通信：所有传输中的数据都必须使用 TLS。为每个端点实施授权策略、速率限制和详细的遥测。

关键交付物

• 一份架构决策记录（ADR），涵盖客户端、服务端和对等节点的角色，定义信任边界，并概述部署假设。
• 正式的 API 或协议规范，以及一套兼容性测试。
• 详细说明发布协调要求的运行手册，例如客户端分批发布、向后兼容性支持，或点对点网络的运维流程。

风险与缓解措施

• “健谈型”客户端：
  • 缓解措施：客户端发出过多小型请求可能导致性能不佳。使用门面或网关等模式整合 API 调用，并在客户端或网络边缘实施缓存策略。
• 包含重复逻辑的“厚客户端”：
  • 缓解措施：客户端包含过多业务逻辑时，往往会导致逻辑重复，并与服务端不同步。可将验证逻辑打包到通用库中共享，或将规则明确移至服务端。
• 点对点数据冲突：
  • 缓解措施：点对点模型中的数据冲突不可避免。应从一开始就设计正式的冲突解决策略（例如 CRDT、最后写入者胜出）和共识机制。

具体组件

以下是此范式的实现通常会包含的工具和抽象术语。它们不是依赖项，也不是 tools: 前置元数据。

• api-contract-generator：生成客户端和服务端共用的机器可读 OpenAPI/RPC 契约
• networking-debugger：捕获请求/响应跟踪信息，用于诊断延迟、重试和超时问题

退出标准

• 已生成 ADR，明确客户端角色、服务端角色（以及适用时的对等节点角色）、信任 边界和所选 API 版本控制策略。
• 已制定正式的 API 或协议规范（OpenAPI、protobuf 或同等规范），涵盖 所有记录在案的端点或能力。
• 在编写任何客户端或服务端代码之前，已记录版本偏差策略（功能标志、Accept 标头或 语义化版本控制）。
• 如果包含离线优先或 P2P 能力，ADR 中已注明冲突解决策略（CRDT、 最后写入者胜出或共识机制）。