第 140 章 配置中心：实现

本章导读

第 139 章把 configd 的设计定案：七层管线（来源→解析→合并→模板→校验→快照→查询）、value 装载域+结构体快照域的分阶段模型、不可变快照+原子指针的交接协议、合并语义显式声明、模板安全三边界。本章是实现章——每条决策逐条落地，且逐条对账：设计章验收标准六条（六 UC 各有正反用例/合并语义向量/热更新竞态/校验带路径/OOM 逐点/装载失败零残留）在实现完成时逐条打勾。项目章的"实现"不是"把设计抄成代码"而是在代码的真实约束下检验设计——本章会展示两处设计与实现的相互修正（模板层从"复用模板引擎"改为"专用展开"——体积预算所迫；提取器从"宏"改为"声明数组+循环"——可测试性所迫），这本身就是设计章"决策可修订"条款的兑现。

140.1引入

实现的起点是验收文件先于源码：把第 139 章练习里手推的三组合并向量（嵌套覆盖/数组替换/类型冲突）写进测试目录的期望文件——它们是合并语义的机器定义；六 UC 的正反用例列成清单——每条实现完跑一遍。开发节奏按七层自底向上：先解析+合并（纯数据变换——最容易测）、再模板+校验（语义层）、后快照+交接（并发层）、最后来源层（文件/HTTP——IO 边界）。每层实现完立即配该层的测试——层的完成定义是"测试绿"不是"代码写完"。这个节奏让最长的那条路（热更新竞态）始终有已验证的地基。

140.2概念

实现的分层地图

本章实现的七层各落在前文哪一章、自写代码有多少——装配与自写的边界图：

二百八十行实现一个带热更新与竞态保证的配置中心——这就是分层库的价值量化：每一层都是某章的正题，项目只写层间胶水与业务语义（合并/模板/规则——真正因项目而异的部分）。与第 145 章 webserv 的"< 400 行"互为印证：XRT 项目的代码量与业务复杂度成正比、与系统复杂度无关——系统复杂度被库层吸收了。

解析与合并层的落地

解析层一步到位：xrtJsonParse（第 32 章）产 value 树——来源字节流（第 45 章文件 Reader 或 HTTP 响应体）到树的纯变换。合并层是本章第一个自写算法（库层没有 value 树深合并——这是 configd 的业务）：

/* 对象递归合并、数组整体替换——语义由测试向量锁定 */
static bool cfg_merge(xvalue* Base, const xvalue* Over)
{
	size_t i;
	if ( !xrtValueIs(Base, XVALUE_OBJECT) || !xrtValueIs(Over, XVALUE_OBJECT) ) {
		return false;   /* 类型冲突：报错带路径 */
	}
	for ( i = 0; i < xrtValueCount(Over); i++ ) {
		xstrview Key;
		xvalue* Ov = xrtValueObjectAt(Over, i, &Key);
		xvalue* Bv = xrtValueObjectGet(Base, Key);
		if ( (Bv != NULL) && xrtValueIs(Bv, XVALUE_OBJECT) &&
			xrtValueIs(Ov, XVALUE_OBJECT) ) {
			if ( !cfg_merge(Bv, Ov) ) { return false; }  /* 递归 */
		} else if ( !xrtValueObjectEdit(Base, Key, Ov) ) {
			return false;    /* 叶子或数组：整体替换 */
		}
	}
	return true;
}

三组向量的锁定：嵌套（db.pool.max 覆盖而 db.pool.min 保留——递归分支）；数组（hosts 整体替换不逐元素——叶子分支）；类型冲突（默认 int 环境给 string——ObjectEdit 替换后类型变了，校验层报路径错）。合并的顺序敏感：default → env 两层固定序——多层扩展时顺序是配置的一部分（声明在装载参数里）。

模板层：从复用到专用的修正

设计章留了两个备选（模板引擎复用 vs 专用展开）。实现的体积核算决定弃复用：模板引擎闭包（第 35 章全套）比 configd 全部其余层加起来还大——为一个 {$VAR} 语法引入整棵模板树不值。专用展开三十行：

/* 合并后、校验前：只环境变量、不递归、未定义报错 */
static bool cfg_expand(xstrview In, xstrbuf* Out)
{
	size_t i = 0;
	while ( i < In.Size ) {
		if ( (i + 1 < In.Size) && (In.Data[i] == '$') &&
			(In.Data[i + 1] == '{') ) {
			size_t j = i + 2, k;
			while ( (j < In.Size) && (In.Data[j] != '}') ) { j++; }
			if ( j >= In.Size ) { return false; }  /* 未闭合 */
			k = j + 1;
			/* 展开值里的 {$ 不再展开（不递归） */
			(void)k;
			{
				char Name[64];
				size_t n = j - (i + 2);
				if ( (n == 0) || (n >= sizeof(Name)) ) { return false; }
				memcpy(Name, In.Data + i + 2, n); Name[n] = 0;
				if ( !cfg_env_append(Out, Name) ) { return false; } /* 未定义报错 */
			}
			i = j + 1;
		} else if ( !xrtStrBufAppendByte(Out, In.Data[i]) ) {
			return false;
		} else { i++; }
	}
	return true;
}

三条安全边界在代码里的位置：cfg_env_append 只查环境（白名单来源——第 43 章）；展开产物不再进展开循环（值里的 {$ 按字面输出——不递归）；未定义变量 cfg_env_append 返回 false（错误带变量名）。这是设计章"决策可修订"的第一处兑现——修订记录进了本章（复用→专用，理由：体积）。

校验层：规则数据化

设计章的"规则是小声明数组"落地为三字段结构（路径/类型/约束）：

typedef struct {
	const char* Path;      /* "server.port" */
	int Type;             /* CFG_T_INT 等 */
	bool (*Check)(long long v);  /* 值域：如 port 1..65535 */
} cfgrule;

static const cfgrule kRules[] = {
	{ "server.port", CFG_T_INT, rule_port },
	{ "server.tls.cert", CFG_T_STR, NULL },
	{ "db.pool.max", CFG_T_INT, rule_positive },
	{ "log.level", CFG_T_STR, rule_level },
};

校验循环：按路径取值（ObjectGet 逐段下钻）→ 类型判定（xrtValueIs 配类型枚举）→ 值域回调。错误路径化的产出口径："db.pool.max: must be > 0"——路径来自规则、消息来自约束回调。新字段加一行规则的维护经济学在此可量化：配置 20 字段 = 20 行规则（与提取器同构）。三层校验一次全查（存在/类型/值域在同一循环）——装载末尾调用，启动即拦（验收 ③）。

交接协议的时序正确性论证

为什么"不可变快照+原子指针"能保证任意时刻整体一致？用一次反面推演：假设快照可变（装载线程边改字段边服务）——查询线程在两次字段读取之间被调度走——回来读到改了一半的配置（port 新值配旧 TLS 路径）——这正是第 139 章坑 3 的竞态。不可变性从结构上消灭这个窗口：快照一旦发布（原子指针替换完成）就无人再写它——查询线程拿到的引用指向的字节永不变化；装载线程构建的是新对象（与旧快照零共享或仅共享不可变部分）。原子指针替换保证发布动作的原子性（读到的是旧指针或新指针——没有中间态）。两个原子合成一个不变量：任意瞬间所有读者看到的配置都是某一次完整装载的产物。长操作的优雅交接由此免费获得：持 Ref 的读者（一次请求的处理过程）继续用旧快照到 Destroy——新读者立即见新——交接没有边界事件（不需要通知、不需要屏障——引用计数自动收敛）。这套论证的测试形态就是竞态测试（10 万次一致性读）——理论、机制、测试三层对齐。

快照层与原子交接

快照提取是 value 域到结构体域的一次性变换。设计修正第二处：提取器从"宏"改为"声明数组+循环"——宏在预处理期展开（调试器看不到）、测试无法逐字段断言；声明数组让提取规则可遍历可测试：

typedef struct {
	const char* Path;
	int Kind;      /* 提取目标类型 */
	void* Slot;    /* 结构体字段地址 */
} cfgslot;

static const cfgslot kSlots[] = {
	{ "server.port", CFG_K_INT, &Snap->Server.Port },
	{ "server.root", CFG_K_STR, &Snap->Server.Root },
	{ "db.pool.max", CFG_K_INT, &Snap->Db.PoolMax },
};

交接协议三件（第 139 章设计原文的落地）：不可变快照——提取完成后结构体只读（文档约定+review 把关——C 无语言级强制；配合第 115 章不可变共享的纪律）；引用计数——快照结构头部嵌通用引用（第 5 章）；原子指针——全局当前快照指针的替换用原子交换（第 9 章）。查询侧 cfg_current() 原子读指针+Ref，用完 Destroy——任意时刻整体一致（验收 ⑥ 的机制）。

装载管线的失败原子性逐层验证

验收 ⑤⑥（OOM 零残留/装载失败零外泄）的机制逐层看：解析层——JsonParse 失败返回 NULL 无部分树（第 32 章原子性）；合并层——cfg_merge 失败时 Base 可能已被部分修改？——这里是本层唯一的弱点：递归合并就地修改 Base——中途失败 Base 处于半合并态。解法：合并的工作副本——装载每次重新解析默认层（或深克隆），在副本上合并——失败丢弃副本、原值无损（工作副本模式——第 134 章失败清理的同构）。模板层——StrBuf 追加失败缓冲丢弃（第 25 章原子性）。校验层——纯读取无修改。提取层——纯拷贝且在全过后。替换层——只在全部通过后原子换指针。逐层失败注入的期望：任何一点失败——全局快照指针未动、读者无感、错误带定位——这正是 OOM 测试逐点断言的内容（第 134 章轮转器跑装载管线）。失败原子性不是"小心写"能保证的——是每层的结构属性叠加的。

来源层与热更新闭环

文件来源：xfile 读全文字节 → 解析层入口（第 45 章）。HTTP 来源：客户端拉取（第 98/99 章）——失败语义按时点分（首次必败/更新可降级——第 139 章 HTTP 追加设计）。热更新闭环：watcher（文件 mtime 轮询或第 48 章异步通知）触发 → 重走装载管线（解析→合并→模板→校验→提取）→ 新快照原子替换 → 旧快照自然退役。失败分支：新配置校验失败——不替换（旧快照继续服务）+告警（第 38 章）——"坏配置不伤运行中的服务"是热更新的安全底线。

交付形态与部署清单

configd 的交付与部署（第 143 章 CLI 契约的服务版）：交付形态——静态库（宿主应用链接——配置中心是被嵌入的组件不是独立进程；第 135 章嵌入章的立场：内存/错误/体积主权在宿主）；裁剪声明 value+template+core 闭包（不含网络——HTTP 来源是可选编译）。API 面三函数：cfg_init(来源参数)（装载+校验+发布首快照——失败返回错误）、cfg_current()（原子取快照 Ref）、cfg_reload()（重走管线——热更新入口）——最小完备：三个函数覆盖六 UC（查询族全走 current 的字段访问）。部署清单：配置文件路径与层级序、环境变量白名单（模板可引用的集合——超出即装载失败）、校验规则表、快照预算（配置树的内存上限——stats 验证）。四项都是声明不是代码——部署工程师不改 C 就能调整——配置系统自身的配置也配置化（自举的一致性）。

扩展路径的预留

第 139 章"与真实配置系统的对照"指出的三个扩展点在实现层的落位：watch 推送（etcd 形态）——来源层加轮询/长连接（第 66/82 章）；替换层不变（快照协议已支持任意频率的替换——协议的前瞻性）；多 profile 组合（Spring 形态）——合并层的层数从 2 到 N：cfg_merge 已是任意两层的二元操作——组合只是装载参数从一对变成有序列表；schema 演进（字段增删）——规则数组与槽位数组加行即完成——数据化的红利。三个扩展的共同点：都不动交接协议——竞态正确性是最贵的属性，设计期把它与业务解耦——业务怎么变协议都不变。这是第 139 章设计最重要的遗产。

与设计章的最终对账

六条验收的逐条对账：①六 UC 正反用例——sub/查询/校验/模板各有正反（实现过程的测试清单全绿）；②合并向量——三组期望文件全绿（合并节的锁定）；③热更新竞态——threads 测试：更新期间并发查询 10 万次零混合态（快照不可变+原子指针的机器证明）；④校验带路径——三条故意违规输入全被拦且错误含路径（校验节的口径）；⑤OOM 逐点——装载管线的失败注入：任一点失败零残留（各层的失败原子+最终不替换）；⑥装载失败零残留——半配置不外泄（快照只在全部通过后替换）。六条全过——configd 可交付。

140.3示例

第一个完整程序：value 装载与查询的原子

下面的程序来自 examples/data/json——解析层与查询层的可运行原子（第 139 章设计章已引、本章作为实现的起点复核）：

 */

#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;
}

刚才发生了什么。 ① 这是 configd 解析层的全部——实现章在其上只加了合并/模板/校验/提取四个纯变换——每层都拿这个原子做开发期验证（层的单测不需要完整管线）。② DOM 查询（ObjectGet 按键取）正是校验层路径下钻的词汇——同一族 API 贯穿装载域的每层（第 31 章 DOM 设计在项目里的兑现）。③ 三种用法选型（头注释：DOM/SAX/Writer）在 configd 的选择：装载用 DOM（需要随机访问与合并——树必须完整）；Writer 不用（配置是输入不是输出）。

第二个完整程序：模板与文件的组合边界

第二个程序来自 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 的能力面（读+编译+渲染+错误偏移定位——头注释）正是"复用模板引擎"路线能得到的一切——能力远超 configd 需要的 {$VAR}。② 修正的量化在此：本示例链接的模板闭包 vs 专用展开的三十行——功能的 thirty 倍换来体积的十倍（体积档数字——第 131 章方法）——错误的交易。③ 但修正不否定备选的价值：配置模板演进到条件/循环时（{$if env=prod}）回到复用路线——扩展点是留下的。

测试文件清单与门禁接线

configd 的测试资产按第 133 章四象限配齐（与实现同 PR 提交——测试不是后补是交付定义）：正向（test_config.c——六 UC 各正例+三合并向量+模板正例——期望文件驱动）；竞态（test_config_threads.c——热更新混合态测试：交替好坏配置的装载线程 × 4 查询线程 × 10 万次一致性读——零混合态断言）；负向（向量含类型冲突/未定义变量/不闭合模板/校验违规四类——错误信息含路径或变量名的精确匹配）；OOM（test_config_oom.c——装载管线逐分配点：任一点失败旧快照不受影响+零残留——第 134 章轮转器直接套用）。门禁接线：全部测试挂 configd 模块清单的 tests 字段（第 130 章）——build.py --suite configd 双轨自动运行；合并向量作为数据文件挂清单 benchmarks 位旁——期望文件与测试同生命周期。这份清单的意义：configd 的下次演进（多层合并/分布式 watch）在任何一行改动后跑一遍就知道有没有破契约——测试资产是项目的记忆。

复盘：实现章的方法论沉淀

configd 实现完成后，与第 138/143/144 章的复盘并置——实现章特有的三条新经验：期望文件先行（手推向量变成机器可判定的期望——设计章练习的产物直接成为实现的测试资产——两个章节的工件衔接）；层的完成定义是测试绿（"代码写完"与"层完成"之间隔着测试——每层实现完立即配该层单测，最长路径（竞态）始终有已验证地基）；修正要留痕（模板复用→专用、提取宏→数组——两处偏离设计的修正连同理由写进本章——可追溯的偏离不是漂移而是演化的记录——第 139 章"决策可修订"条款的工程意义）。加上项目一二四五的累计经验——二十条工程常识在最后两个项目章（140/141）继续检验。

140.4契约

• 管线七层：每层纯数据变换、失败原子；层的完成定义是测试绿而非代码写完。
• 合并语义：对象递归合并/数组整体替换——三组期望文件锁定语义；多层合并顺序是装载参数。
• 模板三边界：只环境变量（白名单来源）/不递归（展开产物不回环）/未定义报错（带变量名定位）。
• 展开时机：合并后、校验前——覆盖优先于注入、校验对着终值。
• 校验数据化：路径+类型+约束的规则数组；新字段一行规则；错误口径"路径: 消息"。
• 提取声明化：路径+目标槽位数组——可遍历可测试（弃宏的工程理由）。
• 交接三件：不可变快照+引用计数+原子指针替换——任意时刻整体一致（竞态测试证明）。
• 热更新安全线：新配置校验失败不替换+告警——坏配置不伤运行服务。
• 失败零残留：装载任一点失败不产生可见状态变化（旧快照继续）。
• 修正记录：复用→专用（模板，体积）/宏→数组（提取，可测试）——设计章条款的兑现。

实现走查：装载主入口的源码

装载管线的主入口——七层串联与替换门（完整程序在教学示例之上，关键段走查）：

/* 装载：来源→解析→合并→模板→校验→提取→替换（全过才换） */
bool cfg_reload(cfgctx* C)
{
	xvalue* Default = NULL;
	xvalue* Env = NULL;
	cfgsnap* Fresh = NULL;
	bool Ok = false;

	/* 1-2 来源与解析：两层各自读+解析（第 32 章原子性） */
	if ( !cfg_load_layer(C, &C->DefaultSrc, &Default) ||
		!cfg_load_layer(C, &C->EnvSrc, &Env) ) {
		goto Done;               /* 失败：指针未动——零残留 */
	}
	/* 3 合并：工作副本上（Env 覆盖 Default） */
	if ( !cfg_merge(Default, Env) ) { goto Done; }
	/* 4 模板：合并后、校验前（三边界在 cfg_expand 内） */
	if ( !cfg_expand_tree(Default) ) { goto Done; }
	/* 5 校验：规则数组一次全查（失败带路径） */
	if ( !cfg_validate(Default, kRules,
			sizeof(kRules) / sizeof(kRules[0])) ) {
		goto Done;
	}
	/* 6 提取：槽位数组纯拷贝（全过后才到这） */
	Fresh = cfg_build_snapshot(Default, kSlots,
		sizeof(kSlots) / sizeof(kSlots[0]));
	if ( Fresh == NULL ) { goto Done; }
	/* 7 替换：原子指针——读者即刻见新 */
	cfg_atomic_swap(&C->Current, Fresh);
	Ok = true;

Done:
	xrtValueRelease(Env);
	xrtValueRelease(Default);
	return Ok;
}

走查要点。 ① 七步顺序即设计章管线——第 7 步是唯一的可见状态变更（前六步全部在局部对象上——失败即丢弃、全局零感知）。② goto Done 的统一清理（两层 value 的销毁）——单出口纪律在管线形态下的样子。③ cfg_merge(Default, Env) 直接在 Default 上合并——靠"Default 每次重新解析"保证无共享（工作副本模式的隐式形态——显式克隆在多来源缓存时才需要）。④ Fresh 成功后归全局所有（swap 后由引用计数接管）——所有权的一次性转移点。

常见错误

xvalue* Bv = xrtValueObjectGet(Base, Key);
if ( Bv != NULL ) {
	xrtValueObjectEdit(Base, Key, Ov);   /* 一律替换：嵌套对象丢了默认层兄弟键 */
}

if ( (Bv != NULL) && xrtValueIs(Bv, XVALUE_OBJECT) &&
	xrtValueIs(Ov, XVALUE_OBJECT) ) {
	cfg_merge(Bv, Ov);                    /* 双侧对象才递归 */
} else {
	xrtValueObjectEdit(Base, Key, Ov);    /* 其余整体替换（含数组） */
}

for ( each rule ) {
	if ( !check(rule) ) { return false; }   /* 失败 */
	extract(rule);                           /* 但前面的已写进结构体 */
}

for ( each rule ) { if ( !check(rule) ) { return false; } }
for ( each slot ) { extract(slot); }        /* 全过才拷贝——纯阶段 */

if ( load(&tree) ) { swap(build_snapshot(&tree)); }  /* 校验呢？ */

if ( load(&tree) && validate(&tree, kRules) ) {
	swap(build_snapshot(&tree));    /* 全过才换 */
} else {
	alert("config reload rejected");  /* 旧快照继续 */
}

编程练习

小结