第9章：服务器开发中的常用模块设计

为什么通用模块必须共享故障语义

重连模块决定何时恢复，心跳决定何时判定失活，日志/错误码解释发生了什么，监控端口告诉调度系统能否继续接流量。若四者各自使用不同 connection id、reason 和时间口径，故障时无法还原同一次事件。

本章以“检测 → 分类 → 恢复 → 解释 → 对外暴露状态”为主线，把原书最后一章的常用模块连接成生产闭环。

9.1 断线自动重连的场景与逻辑

需要断线自动重连的常见场景包括 client 到 service、service 到 dependency、agent 到 control plane。先区分 local shutdown/cancel、DNS/config/auth permanent error、remote refusal、timeout/reset、rate limit 和 network offline；只有可恢复故障进入重连逻辑。

先预测：认证失败、connection refused 和网络离线是否应使用同一重试间隔；再切换图中 failure/attempt，观察 admission decision。

auto Reconnector::next_delay() {
  const auto cap = std::min(max_delay_, base_delay_ * (1ULL << attempt_));
  ++attempt_;
  return random_between(0ms, cap); // full jitter
}

服务器提供 Retry-After 或明确 rate-limit 时优先服从。DNS candidates 轮换、IPv4/IPv6 fallback 和 circuit breaker 也要有总 deadline，避免每层各自重试形成指数放大。

9.2 TCP keepalive 与应用层心跳

TCP keepalive 是 kernel transport probe，在连接长时间 idle 后按平台参数发送 probe，最终发现某些 dead peer/path；它不知道应用 event loop、认证 session 或 dependency 是否健康。应用层心跳包经过协议 handler，可携带 sequence/timestamp 并要求 ack，证明端到端 progress。

int enabled = 1;
setsockopt(fd, SOL_SOCKET, SO_KEEPALIVE, &enabled, sizeof(enabled));
setsockopt(fd, IPPROTO_TCP, TCP_KEEPIDLE, &idle, sizeof(idle));
setsockopt(fd, IPPROTO_TCP, TCP_KEEPINTVL, &interval, sizeof(interval));
setsockopt(fd, IPPROTO_TCP, TCP_KEEPCNT, &count, sizeof(count));

有代理、带业务数据与流量预算

有代理的心跳包机制必须明确每一跳：client↔LB 与 LB↔server 可能是两条 TCP connections，LB idle timeout 也独立。端到端 heartbeat 若被 proxy 本地应答，就不能证明后端 session 存活。

带业务数据的心跳包可捎带 last-seen sequence、load 或 config version，减少额外消息；但会把 liveness 与业务 schema/authorization 耦合。核心 heartbeat 应小、幂等、可独立解析，业务摘要 optional 且受 size/visibility 限制。

心跳包与流量、调试、日志必须一起设计。100 万连接每 5 秒一包，即使单包很小也会形成显著 QPS/带宽和 wakeups；不要只看单连接成本。

9.3 日志模块：从本地调试到集中关联

日志用于回答离散事件的 who/what/when/where/why，不替代 metrics（聚合数值）或 traces（跨服务因果）。日志系统的技术实现至少包括 structured event schema、level/filter、bounded async queue、formatter、rotation/sink、flush/crash policy 与 redaction。

LOG_INFO("connection_closed",
  kv("connection_id", id),
  kv("peer", redacted_peer),
  kv("reason", to_string(reason)),
  kv("error_code", error.code()),
  kv("pending_bytes", pending));

async logger 的 queue 必须有界；满时不能无条件阻塞 event loop。error/fatal 可使用保底同步 sink，低等级按 sampling/drop policy；所有 dropped events 都计数。

网络数据包日志、调试日志与性能日志

在 C/C++ 中输出网络数据包日志时，默认记录 direction、protocol type、length、request id、hash 与有限 hex prefix，而非完整 payload。token/password/cookie/个人数据和密钥必须字段级 redaction；TLS 之前的 plaintext 同样敏感。

PacketLog event{
  .direction = Direction::Inbound,
  .message_type = header.type,
  .payload_length = payload.size(),
  .payload_hash = sha256_prefix(payload),
  .trace_id = trace_id,
};

性能日志记录 operation、duration、queue_wait、bytes、result，并用 monotonic clock；热路径更适合 histogram/trace sampling，不能每次都拼大字符串。debug 时临时提高特定 connection/module 的 level，而不是全局无限 verbose。

分文件、集中式/分布式与业务字段

根据类型写不同文件可隔离 audit/access/error，但会增加 rotation、fd 和查询成本；现代集中式日志服务通常由本地 agent 收集 stdout/file，再送 collector/storage，应用不应同步依赖远端 sink。分布式日志必须传播 trace/span/request id 和一致 clock/field schema。

一条业务日志应包含稳定 event name、result、business entity 的非敏感 opaque id、actor/service、trace id、latency、error code；不要把整份 request object 序列化。敏感信息按 data classification 选择 omit、mask、tokenize 或受控 encryption，且设 retention/access audit。

开发过程中的日志递进缩减

开发阶段可细致 debug，集成阶段收敛到关键 state transition，canary 用 targeted sampling，production 默认 info/warn/error + metrics，incident 再按 module/connection 有时限地动态提升。每次缩减保留能重建生命周期的 started/completed/failed 与 correlation fields。

9.4 错误码系统的作用与设计实践

错误码让程序分支、监控聚合、文档检索和跨服务映射有稳定 identity；human message 可变化/本地化，code 不能复用含义。推荐 namespace + subsystem + category + specific id，例如 CSE-NET-RETRY-003，同时带 retryability、HTTP/RPC mapping、public/internal message 与 cause chain。

struct Error {
  ErrorCode code;
  bool retryable;
  std::string public_message;
  std::string internal_context; // structured and redacted
  std::error_code cause;
};

错误码系统设计实践：集中 registry/生成检查避免重复；owner team 与文档明确；边界层映射而不丢原 cause；日志记录 code + context，metrics 以低基数 category 聚合；不要把 user id/URL 等高基数值嵌入 code。

9.5 监控端口与管理面隔离

监控端口可暴露 /health/live、/health/ready、/metrics、受控 debug/config snapshot。liveness 只说明 process/event loop 活着；readiness 说明是否可接新流量，draining 时应 false；dependency failure 是否影响 readiness 由服务契约决定。

本章回顾：恢复与可观测性是一套状态机

1. 自动重连分类 transient/permanent/cancel，以 capped backoff + jitter 和 single timer 防止重试风暴。
2. TCP keepalive 检测 transport，应用心跳检测 session progress；代理路径、interval、流量和日志需共同预算。
3. structured async logs 默认脱敏、有界；packet/performance 日志按目标采样，生产逐步缩减 detail。
4. 错误码是稳定机器 contract，message/context/cause 另行携带并控制敏感信息。
5. monitoring port 是受保护管理面，live、ready、metrics 与 debug 各有独立语义。

术语表