Instatic 架构测试(Architecture Tests)全指南:95 个结构门禁如何守护自托管 CMS 的工程边界

原创2026-09-15 17:09:441,690 阅读
文章标签:后端前端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 是"源码扫描"门禁的典型代表,源码中有几个值得展开的设计:

  1. 扫描根:只扫 server/ 下导入 DbClient 的文件(!content.includes('DbClient') 直接跳过),因为只有这些文件能发数据库查询,从而避免 options.now ?? Date.now 这类合法 JS 用法误报;
  2. 注释剥离:用 COMMENT_RE 先把行注释/块注释替换为空格(保留行号),避免迁移文件 JSDoc 里提到的 PG 类型名(如 bytea → blob)产生假阳性;
  3. 白名单:migrations-pg.ts、migrations-sqlite.ts、server/db/jsonExtract.ts 是明确豁免对象;
  4. 防腐烂的自检:测试断言 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([])
  })
})

两个值得学习的工程细节:

  1. 注释剥离保留行号——把注释内容替换为等长空格(m.replace(/[^\n]/g, ' ')),违规行号仍与原文件对齐,报告可直接定位;
  2. 防空扫描自检——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. 破坏门禁时怎么办

构建会以具体消息 + 违规文件/行列表失败。分两种情况处理:

  1. 门禁是对的,你的改动是错的——修正你的改动;
  2. 你的改动本身就是新架构,门禁是旧架构——更新门禁。遵循 CLAUDE.md 的规则:"当你的改动偏离结构规则时,在同一次改动中修复该规则的門禁测试。"不要提交门禁已破坏的状态。

从门禁源码看,失败消息设计得极具可操作性:db-postgres-isms.test.ts 会列出 文件:行号 — [模式名] 与 matched: "...",并提示方言等价替代;bundle-size-budgets.test.ts 会给出 actual/budget/rationale 三行并给出两条出路(拆到 lazy 边界,或带一行说明提上限);boundary-validation.test.ts 每条规则都附有规范替代 API 与允许清单。


6. 门禁体系的方法论价值

回顾整个体系,可以从 Instatic 的门禁实践中提炼出几条可迁移的方法论:

  1. 结构规则 = 可执行代码:把"应该怎样组织代码"的约定写进测试,让 CI 替你守住,而不是依赖评审者的记忆。
  2. 防静默失效是门禁的门禁:多处源码都内置了扫描根健全性自检与检测器元测试,防止门禁因目录迁移或正则笔误变成空操作。
  3. 白名单必须带理由:boundary-validation.test.ts 的每条豁免都以 §3.x / §4.x / §5.x 编号并说明工程原因,且接口型深类型的豁免被明确标记为"待跟进 TODO"而非永久豁免。
  4. 安全契约显式冻结:plugin-rpc-target-registry.test.ts 把目标→权限表固化为常量,使任何权限变更成为一次显式的、可评审的安全决策。
  5. 体积预算用静态上限而非基线 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. 延伸阅读

登录后查看全文
Instatic