企业官网建设流程全解析

30-seconds-web 是一个面向代码片段站（30 seconds of code）的网站基础设施项目，它的后端数据层并没有使用 MySQL 等数据库，而是基于一个轻量级的内存 ORM——jsiqle 完成建模。本文带你快速看懂这套数据层设计的思路：8 个模型如何描述"片段、合集、作者"，以及数据是如何从 Markdown/YAML 一路变成 Astro 页面的。

1. 为什么代码片段站需要 ORM？

传统静态站点把内容"拍平"成 JSON，但 30-seconds-of-code 的内容关系其实很复杂：

• 一个片段（Snippet）有作者、语言、标签
• 一个合集（Collection）包含多个片段，且可以嵌套子合集
• 首页、列表页、详情页是不同"视角"下的页面

如果只用裸 JSON + 手写查询函数，过滤、排序、分页、面包屑这些逻辑会散落在各处。30-seconds-web 的做法是：把内容装进一个内存 ORM 数据集，像操作数据库表一样操作内容。

jsiqle 通过 package.json 中的@jsiqle/core引入，整个 Node 侧后端由 src/blocks/application.js 这个Application类统一调度——它负责加载 schema、模型、序列化器，并把数据灌进数据集。

2. 数据模型全景：8 个模型分两层

模型定义集中在 src/blocks/models/ 目录，分为主模型和页面模型两层：

💡 关键设计：内容与页面解耦。Snippet存数据，SnippetPage存"这一页要展示什么"，页面模型永远指向主模型，反过来不行。这样同一个合集可以拆出 p/1、p/2…N 多个页面记录，分页逻辑完全由数据层承担。

3. 关系建模：6 条核心关系

所有模型间关系集中声明在 src/blocks/schema.js，一眼就能看出整个站点的数据流：

• Snippet.author→Author.articles：manyToOne（每个片段属于一个作者）
• Snippet.language→Language.snippets：manyToOne
• Collection.snippets↔Snippet.collections：manyToMany（片段可属于多个合集）
• Collection.parent→Collection.children：manyToOne（合集自引用，实现嵌套导航）
• SnippetPage.snippet：oneToOne；CollectionPage.snippets：manyToMany
• HomePage.snippets / collections：oneToMany（首页聚合入口）

Application启动时会动态加载 src/blocks/models/ 下的全部模型文件，调用jsiqle.create()生成数据集（见 application.js 的setupSchema），并通过Application.models统一暴露给 Writers 和 Serializers 使用。

4. 模型内部结构：fields / properties / scopes

以核心的 src/blocks/models/snippet.js 为例，每个 jsiqle 模型由三部分组成：

4.1 fields：从数据源直接来的"原始列"

fields: { title: 'string', tags: 'stringArray', dateModified: 'date', listed: 'boolean', code: 'object', ... }

对应的是 Markdown front-matter 和正文解析后的字段。

4.2 properties：带缓存的派生属性

这是整个数据层最精华的部分。像seoTitle（自动拼接语言前缀）、breadcrumbs（自动生成面包屑）、searchTokens（搜索分词）、ranking（热度评分）、recommendedSnippets（相似推荐）等业务逻辑，全部以属性形式挂在模型上，并标记cache: true避免重复计算。例如 snippet.js：

seoTitle: { body: snippet => snippet.title.includes(snippet.language.name) ? snippet.title : `${snippet.language.name} - ${snippet.title}`, cache: true, }

snippet.js 中的breadcrumbs属性则直接组合出"Home → 主合集 → 子合集 → 片段"四段面包屑——页面上看到的面包屑导航，本质是一个模型属性。

4.3 scopes：声明式过滤 + 排序

scopes定义了"视角"，让查询像 SQL 一样直观（snippet.js）：

• published/unlisted：过滤条件
• listedByPopularity：已收录 + 按热度排序
• publishedByNew：已发布 + 按时间排序

之后代码里写Snippet.records.publishedByPopularity.slice(0, 20)就能取"前 20 条热门已发布片段"，无需任何手写 filter/sort。collection.js 同样定义了featured、ranked、primary等 scope。

5. 数据流水线：从 Markdown 到内存数据集

整个数据生产是一条清晰的单向流水线：

content/*.md / *.yaml → Extractor 提取 → content.json → populateDataset → 内存数据集 → Writers 输出

1. 提取：src/blocks/extractor/index.js 用 YAML/Markdown 解析器扫描 content/ 目录，提取片段正文、合集配置（collections/**/*.yaml）、作者表、语言表，汇总成一个 JSON 对象并写入.content/content.json（路径由 src/settings/paths.json 定义）。
2. 装载：Application.populateDataset()（application.js）把 JSON 逐条createRecord进各模型，并做三件"数据库级"的事：
   • 按typeMatcher/languageMatcher/tagMatcher为合集自动匹配片段，无需在 YAML 里硬编码 ID；
   • 用batchIterator(cardsPerPage)把合集切片，自动生成CollectionPage分页记录；
   • 组装HomePage记录：最新片段 + 洗牌后的热门片段 + 精选合集。
3. 输出：构建脚本 src/scripts/build.js 并发执行 6 个 Writer（页面 JSON、搜索索引、sitemap、RSS feed、重定向、资源），页面数据由 src/blocks/writers/pageWriter.js 序列化为 JSON，供 Astro 端 src/pages/ 的前置渲染读取。

6. 序列化器：模型与视图之间的"翻译官"

src/blocks/serializers/ 下 4 个 Serializer 解决"同一份数据，多种呈现"的问题：

页面模型的props属性直接调用 Serializer 组装视图数据，例如 homePage.js 里首页的精选合集、片段卡片、SEO 结构化数据（由 schemer.js 生成 schema.org 的TechArticle/ItemList）一次性全部算好。

7. 这套数据层设计值得借鉴的 4 个点

1. 静态站也能有"数据库思维"：用内存 ORM 代替裸 JSON，过滤、排序、分页、关系查询全部声明式完成；
2. 内容与页面分离：SnippetvsSnippetPage的双层结构，让分页、多语言路由、SEO 元数据互不污染；
3. 业务逻辑收敛到模型属性：面包屑、SEO 标题、推荐位都是properties，页面模板只负责渲染，src/components/ 下的 Astro 组件几乎不写业务代码；
4. 单向数据流水线：Markdown → JSON → 数据集 → JSON 页面，每一步可独立测试（见 src/test/ 下的 Jest 用例），开发体验由 src/blocks/application.js 内置的 REPL 控制台进一步加分。

如果你正在为一个内容聚合站做数据层选型，30-seconds-web 这套"轻量 ORM + 分层模型 + 序列化器"的组合，是一个非常适合小团队参考的完整范本。