Instatic 架构测试(Architecture Tests)全指南:95 个结构门禁如何守护自托管 CMS 的工程边界
Instatic 架构测试(Architecture Tests)全指南:95 个结构门禁如何守护自托管 CMS 的工程边界
本指南以 docs/reference/architecture-tests.md 为骨架,结合仓库中的真实门禁测试源码,完整讲解 Instatic(开源自托管可视化 CMS)的架构测试体系:95 个门禁文件覆盖哪些结构领域、三种典型的门禁实现形态、如何运行与新增门禁,以及破坏门禁时的处理流程。读完本文,你将掌握这套"用测试固化结构规则"的方法论,并能直接在 src/__tests__/architecture/ 中定位、阅读乃至设计自己的架构门禁。
1. 架构测试是什么:把结构规则变成会失败的测试
Instatic 的 src/__tests__/architecture/ 目录下存放着一批特殊的测试,官方文档称之为 structural gates(结构门禁)。它们的定位与普通单元测试截然不同:
- 普通单元测试验证"某段代码是否算对了";
- 架构门禁验证"代码库的结构规则是否被破坏",例如:图标只能来自
pixel-art-icons、JSON 列名必须以_json结尾、admin 代码里禁止出现react-router-dom。
这些门禁作为 bun test 的一部分运行,规则一旦被打破,构建就会失败。仓库的 CLAUDE.md 给出了团队协作上的硬性要求:当你的改动偏离了某项结构规则时,必须在同一次改动中修复对应的门禁测试,不允许提交一个门禁已损坏的状态。
从当前仓库看,src/__tests__/architecture/ 实际存在约 100 个门禁文件,覆盖 SQL 方言、JSON 列命名、数据库迁移、CSS token、图标、UI 原语、页面树(page tree)、插件沙箱、AI Agent、路由、内容存储、边界校验、模块体积、认证、错误处理等领域。
1.1 命名约定
门禁文件遵循 kebab-case 命名:<topic>.test.ts 或 <group>-<topic>.test.ts。例如:
db-postgres-isms.test.ts—— 主题在前,简洁明确;plugin-rpc-target-registry.test.ts—— 分组-主题形式;- 少量遗留的
task<N>-*命名(如task414-wrap-to-container.test.ts、task427-preview-class-css.test.ts)仍在守护线上不变量,新门禁一律使用主题名。
1.2 如何运行
在仓库根目录执行:
bun test src/__tests__/architecture/
绝大多数门禁属于导入 / 源码扫描型——它们解析指定范围内的文件并断言/拒绝某些模式;少数属于单元风格(小型内存数据库、合成的页面树)。
提示:仓库
package.json中test脚本即bun test,门禁是其中的一部分;test:bundle则会先执行bun run build再跑包体积预算门禁(见下文 §7)。
2. 按领域分类的门禁全景
以下按官方文档的领域划分,逐类说明每个门禁所守护的结构规则。
2.1 Barrel 导入(Barrel imports)
| 测试 | 守护的规则 |
|---|---|
no-core-barrel-deep-imports.test.ts |
外部调用者必须通过 barrel 导入,不得穿透到具体内部路径(@core/<module>/<file>);模块内部文件则豁免(它们使用相对路径)。作用范围:@core/page-tree、@core/module-engine、@core/visualComponents、@core/publisher、@core/framework、@core/framework-schema、@core/fonts |
阅读 no-core-barrel-deep-imports.test.ts 的源码可以发现一个值得借鉴的细节:扫描时用 OWN_MODULE_DIRS 将每个模块自身目录豁免,并且目录路径带尾部 / 以避免 framework 前缀误匹配 framework-schema;正则以 (?:from|import\()\s*['"]@core/... 同时覆盖静态 from、export … from 与动态 import() 三种形式。这解释了"为什么 barrel 约定值得被门禁"——穿透 barrel 会把调用方重新耦合到模块内部布局,破坏公共面。
相关文档:CLAUDE.md、docs/reference/page-tree.md。
2.2 数据库:schema 与方言(Database — schema and dialect)
| 测试 | 守护的规则 |
|---|---|
db-postgres-isms.test.ts |
导入 DbClient 的文件只允许使用 ANSI SQL,禁止 DML 中的 now()、::int、::jsonb、any($N::...)、distinct on |
db-json-column-naming.test.ts |
每个 PG 的 jsonb 列名必须以 _json 结尾;同一列在 SQLite 迁移中必须为 text |
migration-parity.test.ts |
migrations-pg.ts 与 migrations-sqlite.ts 的迁移 ID 完全一致且顺序相同 |
json-extract-egress.test.ts |
对存储数据的 JSON.parse 必须经由 TypeBox 边界辅助函数 |
db-postgres-isms.test.ts 是"源码扫描"门禁的典型代表,源码中有几个值得展开的设计:
- 扫描根:只扫
server/下导入DbClient的文件(!content.includes('DbClient')直接跳过),因为只有这些文件能发数据库查询,从而避免options.now ?? Date.now这类合法 JS 用法误报; - 注释剥离:用
COMMENT_RE先把行注释/块注释替换为空格(保留行号),避免迁移文件 JSDoc 里提到的 PG 类型名(如bytea → blob)产生假阳性; - 白名单:
migrations-pg.ts、migrations-sqlite.ts、server/db/jsonExtract.ts是明确豁免对象; - 防腐烂的自检:测试断言
SCAN_ROOTS至少解析出一个含.ts文件的目录、且过滤后至少存在一个 DbClient 消费者——防止目录重构后门禁静默扫描零文件(代码注释中明确记录了server/cms/拆分时曾发生的 F-0007 事故)。
migration-parity.test.ts 则展示了"schema 检查"形态:直接导入两侧迁移清单,断言数量相等且 ID 列表 toEqual。其注释还给出了 SQLite 方言对照表——jsonb → text、timestamptz → text、bytea → blob、boolean → integer、now() → current_timestamp、distinct on → window function subquery、一条 ALTER TABLE 多个 ADD COLUMN 需拆分——这正是"迁移失配会让 SQLite 适配器静默缺 schema"这一风险的具体化。
相关文档:docs/reference/database-dialects.md。
2.3 内容存储(Content storage)
| 测试 | 守护的规则 |
|---|---|
data-tables-system-flag.test.ts |
系统表(posts、pages、components)必须播种 system: true |
no-legacy-content-domain.test.ts |
content_* 表/处理器不得回归,一切数据存于 data_* |
no-legacy-pages-table.test.ts |
迁移中不得出现 pages / page_versions 表 |
这三条共同守护 Instatic 的内容存储演进方向:内容数据统一收敛到 data_* 域,系统表由标志位区分。
2.4 页面树(Page tree)
| 测试 | 守护的规则 |
|---|---|
no-vc-mode-branches-in-mutations.test.ts |
11 个 store action 不得按 kind === 'visualComponent' 分支;路由统一收敛到 mutateActiveTree |
visual-components-mutation-contract.test.ts |
VC 树变更必须保持 slot-instance / slot-outlet 不变量 |
centralized-site-mutation-history.test.ts |
所有变更流经单一入口,保证 undo / redo 一致性 |
no-vc-in-site-shell.test.ts |
SiteShellSchema 不声明 visualComponents / pages(它们位于 data_rows) |
page-tree-single-source.test.ts |
表单分析必须复用 @core/page-tree 共享遍历辅助函数,禁止本地递归树遍历/父映射构建 |
multiWrapDefaults.test.ts |
wrapNodes 对整组包裹元素统一应用默认值 |
相关文档:docs/reference/page-tree.md、docs/features/visual-components.md。
2.5 校验 / TypeBox(Validation / TypeBox)
| 测试 | 守护的规则 |
|---|---|
boundary-validation.test.ts |
五条 HTTP / JSON 解析边界规则(详见下文) |
binding-compatibility-coverage.test.ts |
所有端点绑定必须有对应的客户端 schema |
boundary-validation.test.ts 是整个门禁体系中最具代表性的一条,源码把五条规则组织得极为清晰:
- 规则 1:
res.json() as X在src/core/persistence/与src/admin/中被禁止;规范替代是apiRequest(path, { schema })或持有原始 Response 时的readEnvelope(res, Schema, fallback)(均来自@core/http); - 规则 2:
JSON.parse(...) as X在src/core/persistence/中被禁止;规范替代是safeParseJson(raw, Schema)或parseJsonWithFallback(raw, Schema, default)(来自@core/utils); - 规则 3:
src/admin/中禁止裸fetch(——它绕过了credentials: 'include'、统一错误处理与 schema 校验;例外(§3.x 注明理由):流式 NDJSON 与apiRequest无法建模的场景,如agentSlice.ts(§3.1 流式聊天)、useMcpWorkspaceBridge.ts(§3.6 长连接 MCP 桥)、SvgControl.tsx(§3.2 取 SVG 原文内联); - 规则 4:
server/处理器禁止直接req.json(——请求体必须经server/http.ts的单一共享辅助readValidatedBody解析(try/catch + TypeBox 校验集中一处),仅server/http.ts自身豁免(§4.1); - 规则 5:
readEnvelope/parseJsonResponse之后对信封字段做深度类型断言(body.x as DeepType)在src/core/persistence/中被禁止——因为信封只把x校验为Type.Unknown(),断言给出的是虚假的 TS 信心;修复方式是让信封直接引用该字段真实的 TypeBox schema(如FontEntrySchema、SiteDependencyLock、PluginRecordSchema)。仅接口型深类型允许以 §5.x 注明理由(如cmsPlugins.ts§5.1、cmsMediaStorage.ts§5.2),且视为待跟进的 TODO 而非永久豁免。
该测试甚至包含一个"元测试":给检测器喂入合成的 body.font as FontEntry 等正例与 payload.font 等反例,证明规则 5 的扫描器不会因正则笔误而静默变成空操作。
相关文档:docs/reference/typebox-patterns.md。
2.6 错误处理(Error handling)
| 测试 | 守护的规则 |
|---|---|
no-inline-error-ternary.test.ts |
src/admin/ 中所有 catch (err) 必须通过 @core/utils/errorMessage 的 getErrorMessage(err, fallback) 提取错误消息,禁止手写 err instanceof Error ? err.message : fallback |
这条门禁防止每个调用点重新实现该模式而丢失 getErrorMessage 处理空消息回退的能力。
相关文档:docs/reference/error-boundaries.md、CLAUDE.md 的 "Error handling rules" 章节。
2.7 认证 / 能力(Auth / capabilities)
| 测试 | 守护的规则 |
|---|---|
capability-picker-coverage.test.ts |
每个 CORE_CAPABILITIES 条目都出现在 CAPABILITY_META 与某个 CAPABILITY_GROUPS 分组中;同时镜像服务端 CoreCapability 字面量联合与客户端数组——两侧字符串必须一致 |
cms-handlers-capability-gated.test.ts |
server/handlers/cms/ 下每个文件至少调用一次 requireCapability、requireAnyCapability、requireAuthenticatedUser 或 requireStepUp;白名单文件须带明确理由 |
相关文档:docs/features/auth-and-access.md、docs/reference/capabilities.md。
2.8 CSS / 设计系统(CSS / design system)
| 测试 | 守护的规则 |
|---|---|
css-token-policy.test.ts |
src/admin/、src/admin/pages/site/、src/ui/ 下的 CSS Modules 只允许使用 token 变量,禁止裸 hex / rgb / hsl |
css-token-vocabulary.test.ts |
源码与设计文档统一使用当前全局 token 词汇(--bg-*、--text-*、--border*、--overlay-*、--accent-*、语义状态 token),废弃的 editor/panel/rail/tag 别名 token 家族被禁止 |
admin-spacing-token-policy.test.ts |
Admin/共享 UI chrome 使用 globals.css 的流式间距刻度做 margin/padding/gap 与 CSS 绘制的 SVG 尺寸;禁止内联像素间距字符串 |
admin-typography-token-policy.test.ts |
Admin/共享 UI chrome 使用 globals.css 的流式文本刻度;admin/ui CSS module 与编辑器 chrome CSS 中禁止硬编码像素 font-size / font 简写 |
no-css-var-fallbacks.test.ts |
var(--x, fallback) 被禁止——每个 token 必须真实存在,回退值会掩盖漂移 |
noTailwindUtilities.test.ts |
src/admin/、src/modules/、src/ui/ 的 className= 中不得出现 Tailwind 工具类字符串 |
no-tailwind-deps.test.ts |
禁止导入 clsx、tailwind-merge、class-variance-authority、@radix-ui/*、tailwindcss;禁止 @tailwind / @apply 指令 |
scrollbar-chrome.test.ts |
滚动条 token 声明于 globals.css;Firefox(scrollbar-color)与 WebKit/Blink(::-webkit-scrollbar)均以这些 token 样式化;StyleSurface.module.css 使用 scrollbar-gutter: stable 保持属性栏不被覆盖式滚动条遮挡 |
相关文档:docs/design.md、docs/reference/design-tokens.md。
2.9 UI 原语(UI primitives)
| 测试 | 守护的规则 |
|---|---|
button-primitive-usage.test.ts |
src/admin/ 中的裸 <button> 必须走白名单(带 §8 理由) |
ui-primitives-location.test.ts |
原语必须位于 src/ui/components/<Name>/,不得散落 |
no-native-browser-dialogs.test.ts |
禁止 alert()、confirm()、prompt(),改用 Dialog / Toast |
no-native-title-tooltips.test.ts |
禁止用 title= 做悬停提示,改用 <Tooltip> |
no-third-party-icons.test.ts |
禁止 lucide-react、heroicons 等,仅允许 pixel-art-icons |
direct-icon-imports.test.ts |
图标必须深路径导入(pixel-art-icons/icons/<name>),不得从包根导入 |
vendor-icons-fresh.test.ts |
内置图标集必须最新(运行 bun run icons:sync) |
icon-catalog-integrity.test.ts |
每个图标导入均可解析,内置包索引一致 |
close-icon-correctness.test.ts |
关闭操作统一使用标准关闭图标字形 |
no-plugin-tab-shells.test.ts |
role="tablist" 只允许出现在 src/ui/components/Tabs/ 及少量 §T 白名单自定义控件中;src/admin/ 与 src/editor/ 的其他 tablist 必须使用 @ui/components/Tabs 的 <Tabs> / <TabList> |
相关文档:docs/reference/ui-primitives.md。
2.10 编辑器 / 画布(Editor / canvas)
| 测试 | 守护的规则 |
|---|---|
canvasFastRefreshBoundaries.test.ts |
.tsx 文件不得混出组件 + 非组件导出(会破坏 HMR) |
no-circular-dependencies.test.ts |
madge 在 src 与 server 上找到零个 tsconfig 感知的循环依赖 |
canvas-aware-selectors.test.ts |
画布相关 store 选择器必须正确订阅画布状态切片 |
admin-router-usage.test.ts |
内部管理导航必须使用 @admin/lib/routing;禁止裸 /admin 锚点与 react-router-dom |
framework-typography-spacing.test.ts |
站点框架的排版/间距 token 能正确编译 |
component-system-placement.test.ts |
每个 VC 插入流(工具栏选择器、上下文菜单)都必须经由 insertComponentRef;Site Explorer 不得暴露组件到画布的拖拽源;放置文件中禁止直接以 'base.visual-component-ref' 调用 insertNode / addNodeToVc |
task414-wrap-to-container.test.ts |
wrap-to-container 动作创建带默认值的包裹器并保持树结构 |
task427-preview-class-css.test.ts |
预览类 CSS 注入与 publisher 输出一致 |
error-boundary-coverage.test.ts |
每个工作区页面/主要界面都包裹 ErrorBoundary 且带唯一 location 标签 |
non-site-workspaces-no-editor-store.test.ts |
Content、Data、Media 及其共享画布布局不得导入 Site 编辑器 store |
相关文档:docs/editor.md。
2.11 Spotlight
| 测试 | 守护的规则 |
|---|---|
spotlight-no-direct-store-mutation.test.ts |
Providers / scopes 不得直接变更编辑器 store,变更必须收敛在 commands |
keybindings-registry-single-source.test.ts |
每个全局键盘快捷键都必须经过键绑定注册表 |
相关文档:docs/features/spotlight.md。
2.12 插件系统(Plugin system)
插件系统是 Instatic 安全敏感度最高的区域之一,门禁数量也最多:
| 测试 | 守护的规则 |
|---|---|
plugin-rpc-target-registry.test.ts |
RPC 注册表的三重锁定:① 每个 ApiCallSchemas 目标在 apiDispatch.ts 中恰好有一个处理器;② TARGET_PERMISSIONS 的每个 key 都是真实 api-call 目标;③ 完整的 目标→权限 表冻结为已签署的安全契约——任何配对变更都是一次显式的安全决策 |
plugin-bootstrap-fresh.test.ts |
bootstrap/generated/ 生成的引导产物必须与 bootstrap/src/ 的全新打包一致;bun run bootstrap:sync 未执行时失败 |
plugin-sandbox-invariants.test.ts |
插件 bundle 中禁止 node:、bun:、require(、process.binding;网络权限门集中收口于 apiDispatch.ts 并由 TARGET_PERMISSIONS 驱动 |
plugin-boot-resilience.test.ts |
单个坏插件不得拖垮服务器,崩溃被隔离 |
plugin-cms-content-surface.test.ts |
全部五个 cms.content.* 权限必须贯穿所有同步点(权限值、能力矩阵、权限别名构建器、SDK 类型面、host 侧分发) |
plugin-content-access-enforced.test.ts |
cms.content.* 权限授予在 apiDispatch.ts 集中强制(由 TARGET_PERMISSIONS 驱动);各表级处理器额外调用 assertContentTableAccess(manifest contentAccess[] 白名单) |
plugin-content-tree-via-engine.test.ts |
插件内容处理器必须通过 @core/page-tree 的 applyTreeOperation 到达页面树变更,禁止深导入 mutations.ts |
plugin-host-import-boundaries.test.ts |
Worker 传输层(server/plugins/host/)不得导入 apiDispatch——防止池与分发层之间循环依赖 |
plugin-host-ui-runtime-parity.test.ts |
插件 host UI 表面与 SDK 声明的形态一致 |
plugin-schedule-invariants.test.ts |
定时任务的节奏 + 重叠策略在注册时校验;cms.schedule.* 目标由 TARGET_PERMISSIONS 中的 cms.schedule 权限集中门控 |
plugin-secrets-never-leak.test.ts |
HTTP 处理器永不接触插件密钥密文/IV 或明文运行时投影;浏览器端插件设置通过 projectSecretSettings / listPluginSecretStates 投影 |
sandbox-crypto-bridge.test.ts |
插件沙箱的 crypto 表面正确桥接(subtle.digest、subtle.sign);crypto 目标无权限门(纯计算、无 I/O) |
阅读 plugin-rpc-target-registry.test.ts 的源码可以看出一套严谨的安全设计:它从 apiCallSchema.ts 导入 ALLOWED_API_TARGETS 作为目标集合的唯一事实源,通过正则从 apiDispatch.ts 源码中提取 apiHandlers 的 key 做集合相等断言;EXPECTED_TARGET_PERMISSIONS 常量则逐条冻结当前契约——例如 network.fetch → network.outbound、cms.content.entries.update → cms.content.write、cms.content.tree.mutate → cms.content.write。同时明确列出故意无权限门的目标(cms.settings.replace、network.abort、crypto.digest、crypto.signHmac),断言它们存在但不出现在权限表中。这套三重锁定让"某个处理器悄悄改用了不同权限"成为编译错误 + 测试失败的双重拦截。
相关文档:docs/features/plugin-system.md。
2.13 Agent
| 测试 | 守护的规则 |
|---|---|
agent-no-raw-html-in-reply-rule.test.ts |
Agent 系统提示词必须包含 narrate-only 规则(1~2 句回复、回复正文不含原始 HTML/CSS/JSON),防止提示词重构时被误删 |
agent-system-prompt-no-module-enumeration.test.ts |
系统提示词不得枚举 module id——它们在运行时通过 site_list_modules / site_read_document 发现;同时断言 HTML-native 风格标记(site_insert_html、"Structure as HTML, styling as CSS")存在 |
agent-tool-surface.test.ts |
旧的节点构造工具(insertNode、insertTree)与退役的类补丁工具(createClass、updateClassStyles)不得出现在站点写工具列表中;HTML-native 替代(site_insert_html、site_get_node_html、site_replace_node_html)与统一 CSS 编写工具(site_apply_css)必须存在;文档读取、代码资产、设计系统 token 工具、模板工具、快照捕获均须存在;工具总数精确为 29 |
2.14 AI 基础设施(AI infrastructure)
| 测试 | 守护的规则 |
|---|---|
ai-tool-input-object.test.ts |
每个面向 provider 的站点/内容工具 schema 必须是以 type: object 为根的纯对象,根级不得有 anyOf / oneOf / allOf——既匹配 Anthropic 的工具 schema 契约,又维持单一跨 provider 注册表 |
ai-tool-schema-ssot.test.ts |
站点写工具输入 schema 只在 src/core/ai/toolSchemas.ts 定义一次(从 @core/ai 再导出);每个注册工具的 inputSchema 必须是 @core/ai 导出的同一对象(引用同一性检查);消费模块(writeTools.ts、executor.ts、tokenRunners.ts)从 @core/ai 导入且不得重声明本地副本 |
ai-driver-isolation.test.ts |
Provider SDK(@anthropic-ai/claude-agent-sdk、@openai/agents、@openrouter/agent)、zod、@anthropic-ai/sdk 全仓库禁止(无允许调用方);拆分的 @modelcontextprotocol/* v2 包限定作用域:仅允许在 server/ai/mcp/(MCP 服务器)下使用,其余位置(drivers + 浏览器)一律禁止。驱动直接通过 HTTP/SSE 与各 provider 的 REST API 通信,并将 TypeBox schema 作为 JSON Schema 传递。src/ 与 server/ 均被扫描 |
ai-mcp-connectors-never-leak.test.ts |
MCP 连接的 wire 投影(toConnectionView)与 McpConnectionViewSchema 永不暴露个人访问令牌、OAuth 令牌或其哈希(镜像 ai-credentials-never-leak.test.ts) |
ai-driver-shared-helpers.test.ts |
两个跨 provider 辅助函数必须只有一个来源:① parseToolArguments 仅从 server/ai/drivers/http/toolArgs.ts 导出,每个驱动都导入它,私有副本(parseJsonOrEmpty 等)被禁止;② SYSTEM_PROMPT_DYNAMIC_BOUNDARY 只在 server/ai/runtime/types.ts 声明,提示词构建器与驱动导入它。分叉副本会悄悄产生不同的错误处理或破坏各 provider 的提示缓存 |
ai-handlers-capability-gated.test.ts |
server/ai/handlers/ 下每个处理器在干活前必须调用 requireCapability 或 requireAnyCapability,防止未认证访问 AI 端点 |
ai-credentials-never-leak.test.ts |
AI 处理器响应体不得包含凭据密文或原始 apiKey 字段;序列化 CredentialRecord 前必须经 toCredentialView() 投影 |
ai-tools-typebox-only.test.ts |
server/ai/tools/ 下每个文件用 TypeBox 而非 Zod 定义 schema;工具文件要么直接用 TypeBox,要么从 @core/ai(共享 schema 叶子)导入 |
ai-tool-schema-ssot.test.ts 的源码把"单一事实源"门禁做得非常具体:EXPECTED_SCHEMA_BY_TOOL 常量将 29 个工具名逐一映射到从 @core/ai 导入的 schema 对象,然后断言 tool.inputSchema 与期望对象引用同一(toBe),再断言注册工具名集合与映射键集合完全相等;最后对三个消费源文件断言它们 from '@core/ai' 导入且不出现 const insertHtmlSchema = Type.Object(...) 之类的重声明。其注释还点明了历史动机:此前 schema 被声明三次并悄悄漂移,导致服务端约束从未到达浏览器校验器。
相关文档:docs/features/agent.md。
2.15 媒体(Media)
| 测试 | 守护的规则 |
|---|---|
media-migration-invariants.test.ts |
在适配器之间迁移资产必须保留所有变体与引用 |
media-presentation-pipeline.test.ts |
Publisher 的 <picture> / srcset 物化正确 |
media-signed-redirect-serving.test.ts |
/_instatic/media/<adapterId>/<storagePath> 以带新鲜签名的 URL 重定向 |
media-storage-no-bytes-in-sandbox.test.ts |
插件沙箱不能读取原始媒体字节,仅 host 适配器可以 |
media-storage-panel.test.ts |
媒体存储面板 UI 与已注册适配器集合一致 |
相关文档:docs/features/media.md。
2.16 Publisher
| 测试 | 守护的规则 |
|---|---|
dispatcher-html-pipeline.test.ts |
Publisher 的 HTML 管道(sanitize → plugin filters → injections)按顺序执行 |
publish-html-filter-context.test.ts |
插件 publish.html 过滤器收到正确的 context 形态 |
static-artefact-served-before-render.test.ts |
publicRouter.ts 在 resolvePublicRoute 之前调用 readArtefact;当 canonicalRenderQuery(url.searchParams) === '' 时走快路径——垃圾参数(UTM 等)折叠为 '' 直接服务产物,仅影响渲染的循环分页参数(loop_<nodeId>_page)落入实时渲染 |
publish-bumps-cache-version.test.ts |
每个发布/取消发布入口(publishDraftSite、publishDataRow、updateDataRowStatus)都必须调用从 publishState.ts 导入的 bumpPublishVersion(),使 Layer B 在每次访问者可见的状态变更时驱逐 |
hole-runtime-asset-route.test.ts |
路由器必须在 tryServePublicRoute 之前注册 tryServeHoleRuntimeAsset 与 tryServeHole;/_instatic/hole/* 命名空间永不落入 slug 解析 |
module-js-asset-route.test.ts |
路由器必须在 tryServePublicRoute 之前注册 tryServeModuleJsAsset,并从 server/handlers/cms/moduleJs 接线,使 /_instatic/module-js/* 请求不被公开 slug 解析吞掉 |
此外,一个位于 src/__tests__/server/(而非 architecture/)的测试守护着 Publisher 的负载关键性能不变量:
| 测试(server/) | 守护的规则 |
|---|---|
siteCssBundleMemo.test.ts |
buildPublishedSiteCssBundle 按 publishVersion + site 对象 记忆化三个页面无关的 CSS bundle(reset/framework/style):O(全部页面) 的遍历每个发布快照只跑一次而非每次渲染一次;bumpPublishVersion() 使记忆失效;记忆化输出与 buildSiteCssBundle 字节一致;userStyles 每次调用重建(页面作用域,绝不记忆化) |
static-artefact-served-before-render.test.ts 展示了"源码位置检查"这一轻量形态:直接对 publicRouter.ts 做 indexOf 位置比较,断言 readArtefact( 在 await resolvePublicRoute( 之前、readArtefact 从 ./staticArtefact 导入、快路径以 canonicalRenderQuery(url.searchParams) 与 canonicalQuery === '' 为门、且磁盘路径的早返回分支中不出现 applyPublishedHtmlPipeline(该调用只能在 resolver 之后的实时渲染分支)。注释点明了这条门禁守护的核心安全属性:预渲染 HTML 以 ≤ 5 ms TTFB 无 DB 命中提供服务——只有 readArtefact 先于 resolvePublicRoute,缓存命中才能避免 resolver 的 DB 查询。
相关文档:docs/features/publisher.md。
2.17 站点导入(Site import)
| 测试 | 守护的规则 |
|---|---|
siteImport-headless.test.ts |
src/core/siteImport/ 不得导入 src/admin/、server/ 或 react / react-dom 模块,且不含 .tsx 文件——保证 Super Import 管道框架无关、可在无头环境中运行 |
相关文档:docs/features/site-import.md。
2.18 站点迁移:导出 / 导入(Site transfer)
| 测试 | 守护的规则 |
|---|---|
cmsTransferExport.test.ts |
导出必须产生有效的 SiteBundle |
cmsTransferPreview.test.ts |
预览与 apply 实际效果一致(无漂移) |
cmsTransferImport.test.ts |
导入 bundle 得到与源站点等价的结果 |
import-export-roundtrip.test.ts |
完整往返对等:导出 → 导入 → 再导出 = 原始 |
另有一条位于 src/__tests__/server/ 的媒体导入不变量:
| 测试(server/) | 守护的规则 |
|---|---|
importPathTraversal.test.ts |
assertPathWithin 阻止 .. 穿越与绝对路径逃逸;MediaAssetExportSchema.storagePath 模式在 schema 边界拒绝穿越(ISS-009) |
相关文档:docs/features/site-transfer.md。
2.19 Loop 数据源(Loop sources)
| 测试 | 守护的规则 |
|---|---|
loop-source-id-format.test.ts |
Loop 数据源 id 为命名空间小写(base.x、acme.y) |
loop-source-sql-safety.test.ts |
内置 loop 数据源不得发出方言特定或未净化 SQL |
2.20 打包 / 性能(Bundle / performance)
| 测试 | 守护的规则 |
|---|---|
admin-startup-imports.test.ts |
预认证代码(src/admin/preauth/)不得导入 @core/persistence barrel——仅允许窄化的 auth/boot 入口点,保持登录页 chunk 不含 data/media/plugin 客户端 |
bundle-size-budgets.test.ts |
bun run build 后按 chunk 字节预算执行;确保关键 chunk(AdminPageLayout、AdminWorkspaceCanvasLayout、SitePage、ContentPage、CodeMirrorEditor 等)保持在测量上限内 |
module-size-budgets.test.ts |
单模块行数上限:新源模块不得超过 700 行;既有巨型文件的"祖父账本"被冻结且只降不升(bundle-size-budgets 的源码侧兄弟门禁) |
codemirror-lazy-only.test.ts |
CodeMirror 只能通过 lazy() 加载——它体积大,不应进入入口 bundle |
site-editor-shell-lazy-body.test.ts |
强制 SitePage 通过 AdminCanvasLayout 渲染真实外壳(无临时启动骨架);重型编辑器主体(DnD、画布、面板、一厂商模块)保持在绘制后 lazy 边界之后;ImportHtmlModal 保持在打开状态 lazy 边界之后;启动与无站点状态使用 @admin/shared/CanvasFrameSkeleton 的 CanvasFrameSkeletonFrame |
singleInstallManagedHosting.test.ts |
单实例假设在全代码库成立(无多租户泄漏) |
bundle-size-budgets.test.ts 的源码详细说明了预算设计:静态字节上限(当前值预留约 7–10% 余量)而非 diff-against-baseline——后者需要仓库内存储基线文件,会在每个 PR 抖动;Vite 产出哈希文件名(如 layouts-CSneVf19.js),测试按稳定前缀匹配并在测试时解析哈希。典型预算:index- 40 KB、react-vendor- 200 KB、validation-vendor- 125 KB、dnd-vendor- 80 KB(显式预算为 lazy Site 编辑器 vendor chunk,防止 React 启动重新依赖它)、SitePage- 30 KB(必须不拉入编辑器主体)、AdminCanvasEditorBody- 780 KB(绘制后 Site 编辑器主体)、CodeMirrorEditor- 700 KB(最重的 lazy chunk)、typescriptWorker- 7.6 MB。当 dist/assets/ 缺失时门禁自跳过并打 console.warn——规范运行方式是 bun run test:bundle(先构建再测),CI 中构建步骤强制先行所以门禁始终生效。它还附带两个附加断言:react-vendor 不得导入 dnd-vendor-,且图标必须打包为单个 pixel-art-icons-* chunk 而非逐图标产出。
2.21 Docker / 部署(Docker / deployment)
以下测试位于 src/__tests__/server/,守护 Docker 镜像与 Compose 配置的负载关键结构不变量:
| 测试(server/) | 守护的规则 |
|---|---|
dockerConfig.test.ts |
Dockerfile 使用多阶段构建(build → production-deps → runtime);存在 ARG INSTATIC_VERSION 与 OCI 版本标签;TypeScript 路径别名(tsconfig*.json)复制进 runtime 阶段;esbuild 在 dependencies(而非 devDependencies),保证生产环境有运行时脚本打包器。compose.prod.yml 使用 GHCR 镜像、带健康检查、持久卷与 depends_on: condition: service_healthy;POSTGRES_PASSWORD 携带 CHANGEME 占位默认值(无 :? 守卫),使文件在无 .env 的 SQLite 模式下也能加载;INSTATIC_SECRET_KEY 在 .env.production.example 中记录并在 compose.prod.yml 引用 |
相关文档:docs/deployment/。
3. 解剖一个架构测试:三种典型形态
官方文档将门禁归纳为三种形态,每一种都能在当前仓库找到实例。
3.1 源码扫描(Source-scan)
遍历某根目录下的文件,对每行应用正则,断言无匹配(或有特定匹配)。这是最普遍的形式,db-postgres-isms.test.ts、boundary-validation.test.ts、no-core-barrel-deep-imports.test.ts 均属此类。模板如下:
import { readFileSync } from 'fs'
import { describe, it, expect } from 'bun:test'
describe('No `as Foo` at JSON boundaries', () => {
it('every JSON.parse goes through a TypeBox schema', () => {
const offenders: string[] = []
for (const file of walk('src/')) {
const src = readFileSync(file, 'utf8')
if (/JSON\.parse\([^)]*\)\s+as\s+/.test(src)) {
offenders.push(file)
}
}
expect(offenders).toEqual([])
})
})
两个值得学习的工程细节:
- 注释剥离保留行号——把注释内容替换为等长空格(
m.replace(/[^\n]/g, ' ')),违规行号仍与原文件对齐,报告可直接定位; - 防空扫描自检——
db-postgres-isms.test.ts断言扫描根至少含一个.ts文件且至少有一个 DbClient 消费者,boundary-validation.test.ts同样有 SCAN_ROOTS 健全性测试,避免目录重构后门禁静默失效。
3.2 Schema 检查(Schema check)
读取类型化清单(如 pgMigrations)并断言形态。migration-parity.test.ts 是标准示例:
import { pgMigrations } from '../../../server/db/migrations-pg'
import { sqliteMigrations } from '../../../server/db/migrations-sqlite'
it('migration IDs match across dialects', () => {
const pgIds = pgMigrations.map((m) => m.id)
const sqliteIds = sqliteMigrations.map((m) => m.id)
expect(sqliteIds).toEqual(pgIds)
})
plugin-rpc-target-registry.test.ts 的"冻结契约常量"也属于这一家族——不是动态比对两份清单,而是将当前行为逐条固化进 EXPECTED_TARGET_PERMISSIONS,任何变更都必须显式修改契约本身。
3.3 集成风格(Integration-style)
启动小型内存 SQLite、运行迁移、执行代码路径、断言结果:
const db = createSqliteClient(':memory:')
await runMigrations(db, sqliteMigrations)
await createDataRow(db, ...)
const rows = await listDataRows(db, 'posts')
expect(rows).toHaveLength(1)
这适合那些"结构规则"只有真正跑起来才能验证的场景,例如迁移兼容性、往返导出导入(import-export-roundtrip.test.ts)等。
4. 何时新增门禁
官方文档给出了清晰的判定标准。应当新增门禁的场景:
- 结构不变量容易被意外违反(如"所有图标来自
pixel-art-icons"); - 命名约定是负载关键的(如 JSON 列以
_json结尾,因为 SQLite 适配器会自动解析它们); - 目录边界需要强制(如"admin 代码中不得出现
react-router-dom"); - 新权限 / 能力 / 事件类型需要所有同步点接线(如
cms.pages.read存在于 4 处)。
不要为以下情况新增门禁:
- 一次性正确性检查——那属于
src/__tests__/<topic>/的单元测试; - 没有负载关键理由的风格偏好——代码评审就能发现;
- 没有当前风险的"前瞻性防御"——门禁有维护成本。
4.1 命名新门禁
- 使用 kebab-case,主题在前:
<topic>.test.ts或<group>-<topic>.test.ts; - 避免
task<N>/phase<N>/guideline<N>,除非你确实在跟踪进行中的多 PR 重构(重构落地后要改名); - 文件名保持简短——Agent 会 grep 这些名字。
db-postgres-isms.test.ts是好名字,database-dialect-mismatch-detector-no-postgresisms.test.ts是坏名字。
5. 破坏门禁时怎么办
构建会以具体消息 + 违规文件/行列表失败。分两种情况处理:
- 门禁是对的,你的改动是错的——修正你的改动;
- 你的改动本身就是新架构,门禁是旧架构——更新门禁。遵循 CLAUDE.md 的规则:"当你的改动偏离结构规则时,在同一次改动中修复该规则的門禁测试。"不要提交门禁已破坏的状态。
从门禁源码看,失败消息设计得极具可操作性:db-postgres-isms.test.ts 会列出 文件:行号 — [模式名] 与 matched: "...",并提示方言等价替代;bundle-size-budgets.test.ts 会给出 actual/budget/rationale 三行并给出两条出路(拆到 lazy 边界,或带一行说明提上限);boundary-validation.test.ts 每条规则都附有规范替代 API 与允许清单。
6. 门禁体系的方法论价值
回顾整个体系,可以从 Instatic 的门禁实践中提炼出几条可迁移的方法论:
- 结构规则 = 可执行代码:把"应该怎样组织代码"的约定写进测试,让 CI 替你守住,而不是依赖评审者的记忆。
- 防静默失效是门禁的门禁:多处源码都内置了扫描根健全性自检与检测器元测试,防止门禁因目录迁移或正则笔误变成空操作。
- 白名单必须带理由:
boundary-validation.test.ts的每条豁免都以§3.x/§4.x/§5.x编号并说明工程原因,且接口型深类型的豁免被明确标记为"待跟进 TODO"而非永久豁免。 - 安全契约显式冻结:
plugin-rpc-target-registry.test.ts把目标→权限表固化为常量,使任何权限变更成为一次显式的、可评审的安全决策。 - 体积预算用静态上限而非基线 diff:避免基线文件在每个 PR 抖动,约 7–10% 余量既吸收小重构又抓住真回归。
7. 快速上手清单
- 全部门禁:
bun test src/__tests__/architecture/(源码根:src/__tests__/architecture/); - 打包体积门禁:
bun run build && bun test src/__tests__/architecture/bundle-size-budgets.test.ts(或直接bun run test:bundle); - 图标同步门禁触发时:
bun run icons:sync; - 插件引导产物门禁触发时:
bun run bootstrap:sync; - 相关规则书:CLAUDE.md、docs/architecture.md(系统级不变量)、docs/CONVENTIONS.md(文档声明应如何链接门禁)。
8. 延伸阅读
- 门禁源码根目录:src/tests/architecture/
- 数据库方言与迁移:docs/reference/database-dialects.md
- TypeBox 边界模式:docs/reference/typebox-patterns.md
- 页面树单一来源:docs/reference/page-tree.md
- 设计 token 体系:docs/reference/design-tokens.md
- UI 原语规范:docs/reference/ui-primitives.md
- 插件系统安全模型:docs/features/plugin-system.md
- 发布管道与性能:docs/features/publisher.md
- 权限与能力:docs/features/auth-and-access.md、docs/reference/capabilities.md