第 139 章 配置中心：设计

本章导读

项目二是配置中心（configd）：集中管理一组服务的配置——文件或 HTTP 提供 JSON 配置、支持按环境覆盖（默认/开发/生产三层合并）、校验（类型与约束）、可选的模板变量展开（{$env} 注入环境事实）、以及热更新（文件变更重读）。与项目一（第 138 章，一次性工具）的形态差异是本质性的：配置是长期驻留的状态——加载、缓存、被查询、可能更新——生命周期管理与并发访问第一次成为正题。本章是设计章：需求与验收、数据模型选型、分层与模块选型、热更新与并发的语义、校验策略与模板安全——全部在写实现（第 140 章）之前定案。设计章的方法论立场：代码是设计的执行，返工大多源于设计期的含糊。

139.1引入

配置问题看起来平凡——"读个 JSON 嘛"。真实系统里配置的复杂度来自四个维度：来源多样（文件/HTTP 接口/环境变量/命令行——要能组合）；分层覆盖（默认值被环境层覆盖、环境层被实例层覆盖——合并语义要明确）；校验滞后（错误配置在首次使用时才炸——启动期就该拦）；更新传播（改了配置哪些组件要重读、正在使用旧值的操作怎么办）。每个维度处理含糊都会变成线上事故：合并顺序错了生产用了开发的值；校验缺失导致端口 0 照样"启动成功"；热更新竞态让两个线程看到不一致的半份配置。

本章把四个维度各做成明确的设计决策——每个决策都有被否决的备选与理由（第 138 章选型表的方法论扩展到架构级）。下一章的实现将逐条执行这些决策——设计章的可验收性就在于此：实现完成时回头对账，每条决策要么被遵守要么被显式修订。

139.2概念

需求与验收标准

configd 的用例（user story 形式）：UC1 装载——服务启动时从 config.json（或 HTTP 端点）拉取配置，失败则明确报错（不允许静默用空配置）。UC2 分层——default.json → config.{env}.json 两层深合并（深层对象递归、数组整体替换——替换语义显式声明）；UC3 查询——路径式取值（server.port、db.pool.max）带类型期望（取整数给整数，类型不符报错）；UC4 校验——装载期全量校验（必填存在/类型正确/值域合理），错误带配置路径（db.pool.max: must be > 0——第 4 章错误模型的应用）；UC5 模板——字符串值支持 {$ENV_HOME} 展开（环境事实注入配置）；UC6 热更新——文件变更时重装载，新旧配置原子交接（任意时刻查询要么全旧要么全新——不存在混合）。

验收标准（实现章逐条对账）：① 六个 UC 各有正反用例；② 合并语义有测试向量（嵌套覆盖/数组替换/类型冲突）；③ 热更新竞态测试（更新期间并发查询一致性——第 133 章 threads 形态）；④ 校验错误全部带路径；⑤ OOM 逐点（配置装载含分配——第 134 章纪律）；⑥ 装载失败零残留（半配置不外泄——原子性）。

数据模型选型：动态 value 还是专用结构

第一个也是最重要的决策——配置在内存里是什么：

决策：C。理由：配置的演进频率（schema 常变——value 域零成本）与读取频率（热路径每请求可能查——结构体 O(1)）特征不同——分阶段匹配。B 被否决因为合并/模板在结构体域手写太重；A 被否决因为查询路径进热路径。C 的镜像成本用提取器宏控制（每字段一行声明——第 140 章实现）。

分层设计与模块选型

七层各对应前面某章的正题——模块选型全部来自既有章（无新依赖）：这是"项目 = 已有层的重组"命题的再一次验证。层间契约：字节流 → value 树 → 合并后的 value 树 → 校验通过的 value 树 → 结构体快照——每个箭头都是纯数据变换（无副作用、失败原子）。

热更新与并发：原子交接语义

热更新的核心设计是新旧配置的交接协议。configd 的选择：不可变快照 + 原子指针替换。装载产物是不可变结构体（装载后无人改它——天然线程安全，第 115 章不可变共享的配置版）；查询侧持有快照的引用计数指针（第 5 章通用引用——Ref 拿一份、用完 Destroy）；更新 = 构建新快照 → 原子替换全局指针（第 9 章原子操作）→ 旧快照引用归零自然释放。语义保证：任意时刻任何查询者看到的配置整体一致（新旧之一，绝无混合）；正在长操作中的查询者继续用旧快照到操作结束（优雅交接——不强拆）。被否决的备选：全局读写锁（查询热路径进锁——否决）；原地更新可变结构（并发地狱——否决）。

校验分层：语法合法性之外的语义正确性

JSON 解析器保证语法合法（第 32 章）；校验层负责语义：存在性（必填键——缺即错）；类型（值是期望类型——server.port 必须整数）；值域（port 1..65535、pool.max > 0——业务约束）。三层各在装载期一次性执行（启动即拦——不允许"带着错误配置跑"）；错误格式 路径: 消息（db.pool.max: must be > 0）——路径化错误让排障者不用翻整个 JSON。校验规则的表达：小型声明数组（键路径+类型+约束回调）——规则的数据化让新字段加一行规则即可（与提取器宏同构的维护经济学）。

模板展开的时机与注入安全边界

{$VAR} 展开发生在合并之后、校验之前——理由：模板产出可能影响校验（展开后的端口才是要校验的端口）；而合并发生在原始域（默认层的 {$BASE} 被环境层覆盖前不展开——覆盖优先于注入）。安全边界：只展开环境变量（白名单来源——第 43 章）；不递归展开（{$A} 的值里再有 {$B} 不展开——防注入链）；未定义变量报错（不静默空串——配置引用了不存在的环境是部署错误）。这三条是模板层的安全契约——第 77 章密码纪律的配置版：注入面在每个"字符串变配置"的边界都要设防。

139.3示例

第一个完整程序：配置装载的最小闭环

下面的程序来自 examples/data/json——JSON 到 value 的装载与查询（configd 解析层的教科书形态）：

 */

#include <stdio.h>

#include <xrt.h>







 */
static xjsonvisitaction printJsonEvent(
	const xjsonevent* pEvent,
	ptr pUserData
)
{
	(void)pUserData;
	if ( pEvent->HasName ) {
		printf("member: %.*s\n", (int)pEvent->Name.Size, pEvent->Name.Data);
	}
	return XJSON_VISIT_NEXT;
}



int main(void)
{
	xjsonreadconfig ReadConfig;
	xjsonwriteconfig WriteConfig;
	xjsonwriter* pWriter;
	xvalue* pRoot;
	xvalue* pName;
	xstrview Name;
	str sText;
	size_t iSize;

	/* ---- 1) DOM：解析 → 随机访问 → 美化序列化 ---- */
	pRoot = xrtJsonParse(XRT_STR_LITERAL(
		"{\"name\":\"xrt\",\"features\":[\"json\",\"http\"]}"
	));
	if ( pRoot == NULL ) {
		return 1;
	}

	/* ObjectGet 返回借用指针（树拥有它）；GetString 取出视图。 */
	pName = xrtValueObjectGet(pRoot, XRT_STR_LITERAL("name"));
	if ( !xrtValueGetString(pName, &Name) ) {
		xrtValueRelease(pRoot);
		return 2;
	}
	printf("name = %.*s\n", (int)Name.Size, Name.Data);

	/* Stringify 产物是拥有式字符串（xrtFree）；之后树即可释放。 */
	sText = xrtJsonStringify(pRoot, true, &iSize);
	xrtValueRelease(pRoot);
	if ( sText == NULL ) {
		return 3;
	}
	printf("%.*s\n", (int)iSize, sText);
	xrtFree(sText);

	/* ---- 2) SAX：同一份输入按事件流走一遍，不建树 ---- */
	xrtJsonReadConfigInit(&ReadConfig);
	if (
		xrtJsonVisit(
			XRT_STR_LITERAL("{\"code\":200,\"ok\":true}"),
			&ReadConfig,
			printJsonEvent,
			NULL
		) != XJSON_VISIT_DONE
	) {
		return 4;
	}

	/* ---- 3) Writer：增量构建 {"code":200,"message":"OK"} ---- */
	xrtJsonWriteConfigInit(&WriteConfig);
	pWriter = xrtJsonWriterCreate(&WriteConfig);
	if (
		(pWriter == NULL) ||
		!xrtJsonWriterObject(pWriter) ||                     /* 开对象 */
		!xrtJsonWriterName(pWriter, XRT_STR_LITERAL("code")) ||
		!xrtJsonWriterInt(pWriter, 200) ||
		!xrtJsonWriterName(pWriter, XRT_STR_LITERAL("message")) ||
		!xrtJsonWriterString(pWriter, XRT_STR_LITERAL("OK")) ||
		!xrtJsonWriterEnd(pWriter) ||                       /* 闭对象 */
		!xrtJsonWriterFinish(pWriter)                       /* 完整性校验 */
	) {
		xrtJsonWriterFree(pWriter);
		return 5;
	}

	/* Take 移交文本（xrtFree 释放）；Take 后 writer 仍需 Free。 */
	sText = xrtJsonWriterTake(pWriter, &iSize);
	xrtJsonWriterFree(pWriter);
	if ( sText == NULL ) {
		return 6;
	}
	printf("%.*s\n", (int)iSize, sText);
	xrtFree(sText);
	return 0;
}

刚才发生了什么。 ① JSON 文本 → value 树 → 字段查询 → 序列化往返——解析层的完整数据流在十几行里走完。② 查询返回的 value 视图正是 configd 校验层的输入（类型检查对着它做）。③ 这个闭环是第 140 章实现的起点：外面套上"来源层（文件/HTTP）→ 合并层 → 模板层"就是完整装载管线——设计章选的每一层都有这样的可运行原子（第 138 章"示例即门禁"的架构版：设计不是纸上谈兵——每个选型都有已验证的零件）。

第二个完整程序：模板文件装载

第二个程序来自 examples/template/file——模板与文件的组合（模板层的实体参照）：

 */

#include <stdio.h>

#include <xrt.h>



int main(void)
{
	xtemplate* pTemplate = NULL;
	xvalue* pData = NULL;
	str sOutput = NULL;
	int iResult = 1;

	pTemplate = xrtTemplateCompileFile("examples/template/file/page.tpl");
	pData = xrtValueObject();
	if ( (pTemplate == NULL) || (pData == NULL) ||
		 !xrtValueObjectSetNew(
			pData,
			XRT_STR_LITERAL("name"),
			xrtValueString(XRT_STR_LITERAL("Alice"))
		 ) ) {
		goto cleanup;
	}

	sOutput = xrtTemplateRender(pTemplate, pData, NULL);
	if ( sOutput == NULL ) {
		iResult = 2;
		goto cleanup;
	}
	printf("%s\n", sOutput);
	iResult = 0;

cleanup:
	xrtFree(sOutput);
	if ( pData != NULL ) {
		xrtValueRelease(pData);
	}
	if ( pTemplate != NULL ) {
		xrtTemplateRelease(pTemplate);
	}
	return iResult;
}

刚才发生了什么。 ① CompileFile = 读文件 + 编译一步——来源层与模板层的组合件已存在（第 35 章）：configd 的 {$VAR} 展开可以复用模板引擎（变量注入语义一致）或简化为专用的字符串替换（更小）——两个备选都摆着，实现章按体积预算选。② 模板的变量上下文来自 value 树（第 35 章的上下文注入）——与环境变量（第 43 章）的组合就是"配置引用环境"的完整形态。③ 设计启示：展开层的选择不阻塞其他层——分层的好处再次兑现：换展开实现是单层替换。

设计文档的形态：本章即模板

设计章写成什么形态？不是 UML 大图而是决策清单——每条决策五要素：问题（要解决什么）、选项（至少两个备选）、决策（选了什么）、理由（为什么它赢）、验证（怎么知道决策被执行了）。本章的示范：数据模型（三选一，理由是频率分阶段，验证是提取器宏行数）；交接协议（三选一，理由是结构消灭竞态，验证是 threads 测试无混合态）；合并语义（显式声明，验证是测试向量）；模板安全（三条边界，验证是注入用例）。为什么不用 UML：图的歧义空间大（两张图各读出各的意思）而决策清单每条可对账——与 BOOK_SPEC 的门禁哲学同源（可机器判定优先于可human解读）。项目二的这份设计在实现章（第 140 章）开头会被逐条引用——读者将看到"决策→代码"的映射是本章真正的交付物：不是文档而是可对账的约束集。第 141 章聊天服务的设计章沿用同一模板——设计方法论的复用先于代码复用。

从工具到服务：项目一经验的重放

第 138 章复盘的七条经验在 configd 的语境重放——形态变了，经验不变：验收先行（六 UC+六标准 vs 五条——服务的验收要覆盖并发与生命周期，工具不用）；形态决定容器（value 树 vs 计数数组——数据的"演进性"成为新维度：工具的数据形态固定、服务的数据形态可演进）；视图即取即弃（校验层对着 value 视图做、快照层才提取——不提前固化）；分层换件（来源层文件/HTTP 可换 vs Reader 家族——同一纪律升级到七层）；平台事实进设计（服务的平台事实是并发模型与配置文件位置约定）；预算先算（装载一次+查询热路径——预算指认快照层的必要性）；测试四象限（服务加上 threads 与热更新竞态两个象限）。七条全数重放且两条升级——这就是项目序列的教学设计：不是做不同的项目，是同一方法论在不同约束下的深化。

139.4契约

• 验收先行：六个用户故事与六条验收标准——实现章逐条对账，未对账不算完成。
• 模型决策：value 装载域 + 结构体快照域——分阶段匹配演进频率与读取频率。
• 合并语义：对象递归合并、数组整体替换——语义显式声明且有测试向量。
• 原子交接：不可变快照 + 引用计数 + 原子指针替换——任意时刻整体一致。
• 优雅交接：长操作持有旧快照到结束——不强拆。
• 校验三层：存在/类型/值域——装载期一次全查，启动即拦。
• 错误路径化：db.pool.max: must be > 0——错误定位到配置路径。
• 模板安全：只环境变量、不递归、未定义报错——注入面设防。
• 展开时机：合并后、校验前——覆盖优先于注入、校验对着终值。
• 零件已验证：每层选型都有可运行原子（本章两示例）——设计不是纸上谈兵。

HTTP 来源的追加设计（UC1 的网络扩展形态）

文件来源之外，UC1 允许 HTTP 端点——追加设计三要点：客户端装配（第 98 章 easy 层或第 99 章构建器：配置拉取是低频操作，easy 足够；验证器必须——第 85 章"不验证不是选项"在配置场景更严格：配置源被劫持等于全部下游被劫持）；失败语义（拉取失败按 UC1 报错——但可以设计为"失败时沿用上次快照+告警"——降级策略是部署决策：启动首次（无旧快照）必须失败、运行中更新失败可容忍旧配置——两个时点不同策略）；缓存边界（HTTP 响应的缓存语义——第 101 章自动缓存的 only-if-cached 模式正好是"离线时用缓存配置"——四模式在配置场景的精确映射）。HTTP 来源让 configd 从"本地文件工具"升级为"网络配置客户端"——但七层管线只有来源层变（第 138 章分层换件纪律的第三次兑现）。

常见错误

/* 合并行为没写进契约：数组合并看实现心情 */
merge(a, b);   /* 数组逐元素？整体替换？——没人知道 */

/* 契约明写：对象递归、数组替换 + 三组测试向量锁定 */
merge_objects_recursive(); replace_arrays_whole();

int get_port(void) {
	return cfg_get_int("server.port");  /* 首次使用才炸：凌晨 */
}

/* 装载末尾全量校验：存在/类型/值域——启动失败带路径 */
if ( !cfg_validate(&tree, rules) ) { fail_with_path(); }

struct config g_cfg;            /* 全局可变 */
void hot_update(struct config* n) {
	g_cfg.port = n->port;        /* 半新半旧窗口：并发读到混合态 */
	g_cfg.tls = n->tls;
}

cfg_snapshot* fresh = build_snapshot(&tree);  /* 新快照（不可变） */
atomic_swap(&g_current, fresh);               /* 原子换指针 */
/* 读者：Ref 一份→读→Destroy——整体一致 */

编程练习

小结