Design on kenji.blog

Hugo主题自定义：导入Tailwind CSS的方法

Sun, 13 Sep 2026 03:00:00 +0900

前言：静态网站生成器Hugo与Tailwind CSS的强大协同效应

在现代Web前端开发中，兼顾性能与开发体验（DX：Developer Experience）是所有项目中最重要的课题之一。在静态网站生成器（SSG）中拥有世界最快级别构建速度的Hugo，与引入了效用优先（Utility-First）这一创新范式的Tailwind CSS相结合，可以说是对这个课题的终极解答之一。

Hugo使用Go语言编写，即使是数千页的网站，也能在短短几秒或毫秒级的时间内完成构建，拥有惊人的性能。另一方面，Tailwind CSS通过将预先定义好的无数效用类（如flex, text-center, mt-4等）直接写在HTML中，消除了在CSS文件和HTML文件之间来回切换的上下文切换，加速了设计的迭代。

本文将从架构基础到数学层面性能优化的视角，彻底且详细地讲解如何在Hugo主题中导入Tailwind CSS，以及进一步构建使用PostCSS的高级资产管道（Hugo Pipes）的步骤。

1. 效用优先CSS与组件化的演进

在进入Tailwind CSS的导入步骤之前，深入理解为什么我们应该使用Tailwind CSS，以及其背后的CSS设计思想的历史和演进，是非常有益的。

传统CSS设计（BEM或OOCSS）的局限性

在过去的Web开发中，赋予语义化的类名被认为是最佳实践。例如，在创建一个卡片组件时，HTML和CSS通常像这样分离：

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">标题</h2>
 <p class="card__description">说明文本将放在这里。</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* 之后会有更详细的样式 */

这种基于BEM（Block Element Modifier）的设计在项目规模较小的时候还能起作用，但往往会引发以下问题：

命名枯竭与疲劳：每次制作类似的组件时，都必须想出新的类名（例如：card-news, card-featured等）。
CSS体积膨胀：每次添加新功能，CSS的代码行数就会不断增加，而且一旦写好的CSS往往因为害怕“不知道在哪里被使用了”而不敢删除，导致死代码（Dead Code）不断积累。
上下文切换：因为HTML的结构和CSS的样式是在不同的文件中管理的，所以在编辑器中切换标签的次数会呈指数级增长。

Tailwind CSS带来的范式转变

Tailwind CSS通过“效用类的组合”这种方法来解决这些问题。上述的卡片组件如果使用Tailwind CSS，会变成如下形式：

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">标题</h2>
 <p class="mt-2 text-gray-600">说明文本将放在这里。</p>
 </div>
</div>

由于类名本身就代表了样式的具体值（如p-6代表padding: 1.5rem;等），只需看HTML就能预测出最终的渲染结果。此外，通过Tailwind的JIT（Just-In-Time）编译器，只有实际使用到的类才会被提取到生产环境的CSS文件中，因此CSS的文件大小会被极限压缩。

2. Hugo Pipes与PostCSS的架构

为了将Tailwind CSS集成到Hugo中，必须了解名为Hugo Pipes的资产处理管道。Hugo Pipes是一项强大的功能，它能够在Hugo内部完成诸如Sass/SCSS编译、JavaScript打包和压缩，以及这次我们要使用的PostCSS的执行等所有关于资产的处理。

PostCSS是一个使用JavaScript插件来转换CSS的工具。Tailwind CSS本身实际上也是作为PostCSS的一个插件来运行的。

PostCSS的AST（抽象语法树）转换机制

了解PostCSS是如何处理CSS的，对于进行故障排查非常有帮助。下面的Mermaid图展示了PostCSS读取CSS文件，通过插件进行转换，直到输出最终CSS的管道流程。

flowchart TD
A["原生CSS (styles.css)"] -->|Parser| B["AST (抽象语法树)"]
B --> C["插件 1: Tailwind CSS"]
C --> D["插件 2: Autoprefixer"]
D --> E["插件 N: cssnano"]
E -->|Stringifier| F["编译并优化后的CSS"]

Parser（解析器）：解析输入的原始CSS字符串，将其转换为程序可以操作的数据结构，即AST（抽象语法树）。
Plugins（插件群）：
- Tailwind CSS：扫描模板文件（HTML或Markdown），将在其中使用的效用类作为节点添加到AST上。同时，它还会展开@tailwind指令。
- Autoprefixer：参考Can I Use的数据库，根据需要将浏览器引擎前缀（如-webkit-, -moz-等）添加到AST的属性中。
Stringifier（字符串化器）：将转换完成的AST再次转换为浏览器可以解析的CSS字符串并输出。

3. 环境搭建与前提条件

那么，让我们进入实际的导入步骤。首先确认是否已安装所需的软件。

必备要求

Hugo Extended Version：不是普通的Hugo，而是必须包含Sass/SCSS处理功能以及原生支持PostCSS集成功能的Extended版。在终端中执行以下命令，确认版本信息中包含extended字符串。
1 2 3

hugo version # 预期的输出示例: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js与npm： Tailwind CSS和PostCSS等依赖包需要在Node.js上运行。请确认已安装Node.js（推荐LTS版）。
1 2

node -v npm -v

安装npm包

在项目的根目录（即Hugo的配置文件hugo.toml所在的层级）初始化npm，并安装所需的包。

1
2
3
4
5


# 生成package.json
npm init -y

# 安装Tailwind CSS, PostCSS, Autoprefixer作为开发依赖
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] 如果没有安装postcss-cli，当Hugo内部调用PostCSS时可能会发生错误。因为Hugo Pipes内部使用postcss-cli，所以请务必安装它。

4. 构建配置文件（PostCSS & Tailwind CSS）

包安装完成后，创建两个控制项目行为的重要配置文件。请将它们放在项目根目录下。

创建 tailwind.config.js

在终端中执行以下命令，将会生成默认的配置文件。

1

npx tailwindcss init

使用编辑器打开生成的 tailwind.config.js，设置 content 属性。这里非常重要。Tailwind会解析这里指定路径的文件，并提取其中使用的类。请根据Hugo的项目结构，准确地指定布局文件和内容文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // 根据Hugo的目录结构指定扫描目标
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // 如果使用了主题，也必须包含主题的目录
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // 在这里进行自定义颜色和字体的扩展
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // 根据需要添加官方插件（例如：Typography插件）
 // require('@tailwindcss/typography'),
 ],
}

创建 postcss.config.js

接下来，在项目根目录创建 postcss.config.js，用来定义PostCSS执行哪些插件以及执行的顺序。

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

通过这个配置，当Hugo调用PostCSS时，会首先进行Tailwind CSS的处理，然后再由Autoprefixer进行添加浏览器前缀的处理。

5. 在Hugo中构建CSS资产管道

配置完成后，终于可以将Tailwind CSS集成到Hugo主题端了。

5-1. 创建作为入口点的CSS文件

在 assets/css/ 目录（如果不存在请创建它）中，创建一个作为入口点的CSS文件。在这里我们命名为 main.css。

文件路径: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* 导入Tailwind的基础样式（如重置CSS等） */
@tailwind base;

/* 导入组件类 */
@tailwind components;

/* 导入效用类 */
@tailwind utilities;

/* 如果需要自定义CSS，可以写在这里，
 但建议尽可能在tailwind.config.js的extend中进行处理 */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. 编辑布局文件（head.html）

接下来，在Hugo的模板中读取上述的CSS文件，并编写使用PostCSS处理的管道。通常需要编辑定义了 <head> 标签内的局部模板（例如：layouts/partials/head.html）。

文件路径: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- 获取 assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- 定义PostCSS选项 -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- 面向生产环境（Production）的资产优化管道 -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify（压缩） -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint（用于缓存破坏的哈希计算） -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. 输出带有SRI（子资源完整性）的标签 -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- 在开发环境（Development）中不压缩，直接输出（优先考虑构建速度） -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

管道说明与Mermaid图解

下面通过图解说明上述的Go模板代码是如何处理CSS文件的一系列管道流程。

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo内存空间"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT 处理"]
C --> D{"hugo.IsProduction ?"}
D -- Yes (生产环境) --> E["minify (删除空格与换行)"]
E --> F["fingerprint (计算哈希)"]
F --> G["public/css/main.[hash].css (带SRI)"]
D -- No (开发环境) --> H["public/css/main.css"]

resources.Get：在assets目录中查找指定的文件，并将其作为内存中的资源对象加载。
resources.PostCSS：参考项目根目录的postcss.config.js，将Tailwind CSS和Autoprefixer的处理应用到CSS源代码中。在开发环境（hugo server）下，JIT模式会启动，在文件变更时能高速生成所需的类。
minify：在生产环境构建时（例如hugo --environment production），删除不需要的空格和注释，最小化文件大小。
fingerprint：根据文件内容计算SHA哈希值，并附加在文件名上（例如：main.ab12cd...css）。这使得可以在利用浏览器强大的缓存机制的同时，在CSS更新时可靠地加载新文件，实现了“缓存破坏”。
integrity：利用Fingerprint计算出的哈希值，输出SRI属性以防止来自CDN等的篡改。

6. CSS优化中的数学性能分析

引入Tailwind CSS最大的优点之一，就是将分发的CSS文件大小减小到极致。让我们使用数学模型来定量分析这会对Web性能（特别是首次内容绘制：FCP）产生怎样的影响。

CSS文件大小缩减模型

在传统的CSS框架（如Bootstrap等）中，因为包括未使用的样式在内的全部代码都会被加载，所以文件大小 $S_{original}$ 往往会很大（约150KB～200KB）。假设Tailwind CSS的JIT编译器清除了（Purge）未使用的类后的大小为 $S_{purged}$，使用缩减率 $R_{purge}$ 可以表示为：

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

在典型的项目中，$R_{purge}$ 会接近 $0.9$（减少90%），$S_{purged}$ 将缩小到仅有10KB～20KB左右。

此外，在分发时服务器端会进行Brotli或Gzip压缩。如果压缩率为 $R_{compress}$（通常在0.7～0.8左右），在网络中流动的最终负载大小 $S_{final}$ 将通过以下公式计算：

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

关键渲染路径与网络延迟

浏览器在屏幕上绘制出第一个内容的时间（FCP），可以近似为HTML下载时间、CSS下载时间与渲染时间之和。

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

这里：

$RTT$ : 往返时间（与服务器之间的往返通信延迟时间）
$BW$ : 网络带宽（Bandwidth）

在移动网络等 $BW$ 较窄、$RTT$ 较大（延迟大）的环境中，Tailwind CSS将 $S_{final}$ 削减到几千字节级别的方法，能将 $\frac{S_{final}}{BW}$ 这一项极度趋近于零，成为在Google PageSpeed Insights等工具中获得惊人高分的驱动力。

7. 启动开发服务器并验证热重载

所有配置完成后，启动Hugo的开发服务器，确认Tailwind CSS是否正常工作。

1

hugo server -D

在浏览器中访问 http://localhost:1313/，确认网站已显示。尝试打开Markdown内容文件或Hugo的模板（layouts/ 下的文件），并添加一些类。

1
2
3
4
5


<!-- 用于测试的Tailwind类应用示例 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">请确认热重载是否能够瞬间生效。</p>
</div>

保存文件的瞬间，Hugo强大的文件监听器和Tailwind的JIT编译器将协同工作，让你体验到在几毫秒内重新构建CSS并自动刷新浏览器（热重载）的快感。

故障排查：样式未生效的情况

如果更改未生效，请检查以下几点：

tailwind.config.js 中的 content 路径设置 如果扫描目标的文件路径错误，Tailwind将无法检测到该文件中使用的类，也不会将其输出到CSS中。特别是在使用主题的情况下，请确认是否遗漏了主题目录的路径。
PostCSS错误 如果终端中Hugo服务器的日志输出了类似 Error: failed to transform resource: PostCSS not found 的错误，可能是 npm install 未正确执行，或者缺少 postcss-cli。
清除Hugo缓存 在极少数情况下，因为Hugo的缓存问题可能会残留旧的CSS。请尝试停止服务器，然后使用 hugo server --ignoreCache 启动，或者删除OS的临时目录（如 /tmp/hugo_cache/ 等）。

8. 面向生产环境的构建与进一步进阶

在将网站部署到生产服务器（如Netlify, Vercel, GitHub Pages, Cloudflare Pages等）时，需要设置环境变量来运行生产用的优化管道。

1
2


# 生产构建命令示例
NODE_ENV=production hugo --minify --environment production

加上 --environment production 标志后，head.html 中的 {{ if hugo.IsProduction }} 代码块会被执行，从而进行CSS的Minify压缩和添加Fingerprint哈希。

使用Typography插件为Markdown添加样式

在像Hugo这样的博客或文档网站中，我们无法直接向由Markdown生成的纯HTML元素（如 <h1>, <p>, <ul> 等）添加类名。在这种情况下，非常有用的是Tailwind官方的 Typography插件。

安装插件

1

npm install -D @tailwindcss/typography

添加到 tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

在模板中应用只要在输出文章正文的容器元素上添加 prose 类（以及你喜欢的颜色或尺寸的变体），就能应用优美的默认样式。
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

通过这种方式，就完全不需要手写复杂的CSS选择器（如 .article-content h2 { ... }）了，从而完美地保持了组件的模块化。

9. 总结：高可维护性前端生态系统的完成

辛苦了。至此，一个兼备Hugo超高速静态站点生成引擎、Tailwind CSS现代样式功能以及PostCSS可扩展性的完美的Web开发资产管道就完成了。

这种架构的优点在于**“配置只需进行一次即可”**。一旦搭建好管道，开发者就无需打开CSS文件，只需直观地将效用类写在HTML或Markdown模板中，便能以惊人的速度搭建出复杂的UI。

此外，由于输出的CSS大小总是被最小化的，这直接提升了Core Web Vitals的分数，从SEO的角度来看也非常有利。

Hugo与Tailwind CSS的组合，无论是对于个人的技术博客还是大型的企业网站，在所有项目中都将继续是“最佳选择”之一。请务必活用这条强大的工具链，享受舒适的Web开发生活吧！

博客深色模式支持中的CSS设计要点

Sat, 12 Sep 2026 12:00:00 +0900

现代Web开发中，深色模式（Dark Mode）的支持已经从单纯的“锦上添花的特性（Nice to have）”转变为提升用户体验（UX）的“必备要求（Must have）”。特别是像博客和文档网站这样需要长时间阅读文本的媒体，它能够减轻用户的眼睛疲劳，并降低设备的电池消耗，因此支持深色模式的重要性可以说是极高的。

本文将从前端工程师的视角，极其深入地剖析博客在适配深色模式时不可避免的技术挑战和高可维护性CSS设计要点。涵盖的内容包括：利用CSS Custom Properties（CSS变量）、防止FOUC（Flash of Unstyled Content）的高级JavaScript控制与SSR结合、确保无障碍访问（WCAG 2.1 AAA）的色彩设计（RGB、HSL以及最新的OKLCH），还有使用Tailwind CSS的实用代码示例，网罗深色模式实现的方方面面。

1. 基于CSS Custom Properties（CSS变量）的主题设计基础

在实现深色模式时，目前最标准且强大的方法是利用 CSS Custom Properties（CSS变量）。与Sass等CSS预处理器的变量（$color）在编译时静态解析不同，CSS变量是在浏览器的运行时动态解析和覆盖的。由此，只需通过JavaScript切换类名，即可瞬间改变整个页面的色调。

1.1 基本色彩主题的定义

首先，使用 :root 伪类定义浅色模式（默认）的调色板。然后，当赋予 [data-theme='dark'] 等属性（或 .dark 类）时，对这些变量进行覆盖，这是最经典的设计模式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* 浅色模式（默认）的变量定义 */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* 深色模式时的变量覆盖 */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* 实际应用 */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

如此这般，通过将布局或排版的指定与颜色（主题）的指定完全分离，CSS的可维护性将会实现飞跃性的提升。

1.2 灵活运用 @media (prefers-color-scheme: dark)

如果操作系统级别设置了深色模式，从用户首次访问网站开始自动应用深色主题，从UX的角度来看是更理想的。实现这一点的正是 @media (prefers-color-scheme: dark) 这个媒体查询。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* 当操作系统的环境设置为深色模式时的回退方案 */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

在这种写法中，除非用户明确选择了浅色模式（data-theme='light'），否则会尊重操作系统的深色模式设置来覆盖变量。

2. 理解色彩空间与无障碍访问（WCAG 2.1 AAA）

在深色模式的色彩设计中，仅仅“把背景变黑，文字变白”是不够的。如果对比度过强，会引起光晕现象反而难以阅读；而如果对比度过低，又会损害可视性。Web Content Accessibility Guidelines (WCAG) 对确保可视性的对比度进行了严格的定义。

2.1 WCAG 对比度计算公式

WCAG 中的对比度（Contrast Ratio） $CR$ 使用背景色和前景色（文本色）的相对亮度（Relative Luminance）定义如下：

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

这里，$L_{lighter}$ 是较亮颜色的相对亮度，$L_{darker}$ 是较暗颜色的相对亮度（值的范围是 0.0 到 1.0）。为了达到 WCAG 2.1 的 AAA 级别，常规文本需要 7:1 以上，大文本需要 4.5:1 以上 的对比度。

相对亮度 $L$ 可由 sRGB 色彩空间的 RGB 值通过以下复杂的公式计算得出：

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

各分量（$R, G, B$）是使用原有的 8 位值（$R_{sRGB}$）除以 255 后的归一化值，为解除伽马校正进行如下转换：

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

手动进行这样的计算很困难，但通过利用色彩设计工具，可以机械地挑选出满足对比度 7:1 ($CR \ge 7.0$) 的颜色。

2.2 HSL vs RGB vs OKLCH

在创建调色板时，过去 RGB 或 HSL 是主流。然而，从“感知均匀性”的角度来看，它们有着巨大的缺陷。

RGB: 机械的光学三原色，人类难以直观地进行“调亮”或“调暗”之类的调整。
HSL: 使用色相 (Hue)、饱和度 (Saturation) 和亮度 (Lightness)，但 HSL 的“亮度 (L)”与人类眼睛感知的亮度并不一致。例如，在 HSL 中亮度同为 50% 的纯黄色和纯蓝色，在数值上亮度相同，但在人眼看来黄色却亮得多。
OKLCH: 近年在 CSS Color Module Level 4 中引入的最新色彩空间。由 Lightness（感知明度）、Chroma（饱和度）、Hue（色相）组成，完全符合人类的视觉特性（感知均匀）。

通过使用 OKLCH，即使改变色相（Hue）也能保持相同的感知明度（Lightness），这使得为深色模式生成调色板变得极具可预测性且安全。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* 使用 OKLCH 定义 CSS 变量的示例 */
:root {
 /* 浅色模式的基础明度较高，饱和度较低 */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* 在深色模式中只需反转明度，即可轻松保持感知对比度 */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* 针对深色模式稍作提亮以确保可视性 */
}

这样通过采用 OKLCH，就能非常简单地构建起在多个主题间保证一致对比度（WCAG AAA 水平）的逻辑。

3. 防止FOUC（Flash of Unstyled Content）与SSR水合作用

在支持深色模式时最令开发者头疼的，就是被称为 FOUC (Flash of Unstyled Content) 的画面闪烁问题。

3.1 客户端 JS 切换主题的陷阱

在 React 或 Vue 等 SPA（或 SSG 生成的静态网站）中，将用户的设置保存在 localStorage，然后用 JavaScript 读取并切换主题是常见的做法。然而，如果在 React 的 useEffect 等中执行此操作，就会发生以下问题：

浏览器渲染浅色模式的 HTML/CSS。
JS 包被加载并执行。
从 localStorage 读取 dark 设置。
HTML 被赋予 dark 类，画面突然变暗（闪烁）。

为了彻底防止 FOUC 并避免水合错误（Hydration Error），最佳实践是 将用户的主题设置保存在 document.cookie 中，并在服务器端渲染（SSR）阶段返回赋予了合适类名的 HTML。

以下的时序图展示了利用 Cookie 进行主题初始化的理想流程：

sequenceDiagram
participant User as "用户"
participant Browser as "浏览器 操作系统"
participant Server as "服务器 SSR"
participant DOM as "客户端 DOM"
User->>Browser: "请求页面"
Browser->>Server: "携带 Cookie (theme=dark) 的 GET 请求"
Server-->>Browser: "返回包含 <html data-theme='dark'> 的 HTML"
Browser->>DOM: "渲染初始 HTML (无 FOUC)"
DOM->>DOM: "执行水合脚本"
alt "无 Cookie (首次访问)"
DOM->>Browser: "检查操作系统 prefers-color-scheme"
Browser-->>DOM: "matchMedia 结果 (例如 dark)"
DOM->>DOM: "通过内联阻塞脚本设置 data-theme='dark'"
end

对于仅支持 SSG（静态网站生成）且无法进行 SSR 的博客（例如 Hugo、Gatsby 或 Astro 的静态导出等），必须在 <head> 标签内部放置会阻塞渲染的内联 JavaScript，并在 DOM 渲染前一刻赋予相应类名，这是必不可少的方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 放置在 <head> 内部的最后 -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

这段简短的脚本会阻塞浏览器的渲染并立即执行，因此在画面渲染时就已经设置好了 data-theme 属性，能够彻底防止画面的闪烁（FOUC）。

4. Tailwind CSS 与原生 SCSS/CSS 的实现方法

将深色模式引入实际项目时，需要了解各个工具的实现方法。

4.1 Tailwind CSS 中的深色模式

Tailwind CSS 默认提供了 dark: 变体（variant），可以非常简单地实现深色模式。在配置文件（tailwind.config.js）中设置 darkMode 属性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (依赖操作系统设置) 或 'class' (可手动切换)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* 利用 CSS 变量扩展 Tailwind 的调色板 */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

在 HTML 方面只需像下面这样添加类名即可。

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

然而，对所有元素都写上 dark:bg-xxx 也会成为组件变得臃肿的原因。在大型博客或应用程序中，推荐采用以 CSS 变量为基础，从 Tailwind 引用这些 CSS 变量的混合设计（语义化颜色设计）。

以下是展示 CSS 变量继承和应用层级的类图：

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "应用工具类"

4.2 使用原生 SCSS/CSS 实现（活用 Mixin）

在不使用 Tailwind 而独立编写 SCSS 的项目中，可以利用 @mixin 将深色模式的样式封装起来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* SCSS Mixin 的定义 */
@mixin dark-mode {
 /* 支持 [data-theme='dark'] 属性，或操作系统设置 */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* 使用示例 */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

这种方法虽然直观，但编译后的 CSS 文件体积容易膨胀（媒体查询会被复制到各个选择器中），因此目前的趋势仍然是过渡到以 CSS 变量（Custom Properties）为核心的设计。

5. 图片（Image）与 SVG 的深色模式优化

即使文本和背景的色彩设计已经完成，如果作为内容放置的图片或图标（SVG）仍然保持浅色模式的状态，在深色模式下就会显得非常刺眼且格格不入。对它们进行优化也是必不可少的。

5.1 降低图片亮度的 CSS 滤镜

如果将照片等位图图像在深色模式下原样显示，有时会过于刺眼。通过使用 CSS 的 filter 属性，稍微降低图像的亮度（brightness）并增加对比度（contrast），就能使其自然地融入深色主题的 UI 中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* 降低亮度，稍微提高对比度 */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* 悬停时恢复原有的亮度（为了用户想要查看细节的情况） */
 filter: brightness(1) contrast(1);
}

5.2 使用 `<picture>` 标签切换图片

像 Logo 或说明用的图解（如背景固定为白色的 JPEG）等，仅靠滤镜处理是无法解决的。在这种情况下，正确的做法是结合 HTML 的 <picture> 元素和媒体查询，为深色模式提供另一份图片文件。

1
2
3
4
5
6


<picture>
 <!-- 向系统设置为深色模式的用户显示这张图片 -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- 默认（浅色模式） -->
 <img src="/img/logo-light.png" alt="网站 Logo">
</picture>

※需要注意的是，这种方法不会与 localStorage 等手动切换功能联动（仅依赖于操作系统设置）。如果实现了手动切换，则需要使用 JS 动态修改图片的 src，或者通过 CSS 类切换 display: none。

5.3 SVG 图标的 `currentColor` 适配

对于图标等处使用的内联 SVG，将其填充颜色与父元素的文本颜色联动是最高明的做法。只需将 SVG 的 fill 或 stroke 属性指定为 currentColor 即可。

1
2
3
4


<!-- CSS 的 color 属性的值（例如 var(--text-primary)）将自动被应用 -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

由此一来，当切换到深色模式，父元素的文字颜色变成白色系时，SVG 图标也会自动变为白色系。

6. 总结：迈向可持续的深色模式设计

在博客或 Web 应用程序中，要实现高质量的深色模式，涵盖以下要点的 CSS 设计是不可或缺的：

活用 CSS Custom Properties（CSS变量）: 避免硬编码颜色指定，将其抽象为语义化的变量名（例: --bg-primary）。
采用 OKLCH 色彩空间: 在感知均匀的色彩空间中进行符合逻辑的设计，以满足 WCAG 2.1 AAA 标准中高无障碍访问的对比度（7:1 以上）。
彻底做好 FOUC 防御对策: 结合 SSR 和 Cookie，或使用 <head> 内的阻塞式内联脚本，彻底消除初次加载时的画面闪烁。
媒体与静态资源的优化: 充分运用 filter: brightness()、currentColor 以及 <picture> 标签，使文本以外的元素也能与深色主题相得益彰。

超越了单纯的“颜色反转”，正是这些细致入微的考量，才能被称为是一个能够长期受用户喜爱、提供不伤眼且卓越阅读体验（Reading Experience）的现代博客的条件。准备引入深色模式的开发者们，请务必参考本文的设计模式。

软件架构基础：什么是整洁架构？

Sat, 12 Sep 2026 12:00:00 +0900

现代软件开发中，构建“拥抱变化的系统”是一个永恒的课题。业务需求的变更、新框架的崛起、UI的翻新、数据库的迁移。面对所有这些变化，我们需要一种能够灵活适应且无需重构整个系统的架构。作为其中的一个答案，Robert C. Martin（被戏称为Bob大叔，Uncle Bob）提出了整洁架构（Clean Architecture）。

本文将通过整洁架构的历史、目的、四个分层的细节、依赖规则以及具体的代码实现，深入探讨整洁架构的精髓。我们将进行非常深入且详细的技术解析。

1. 传统架构的问题与整洁架构的历史

从历史上看，软件架构经历了各种范式转变。在早期的系统中，业务逻辑、UI、数据访问代码紧密耦合（所谓的意大利面条代码）。此后，为了实现关注点分离（Separation of Concerns），三层架构（表现层、业务逻辑层、数据访问层）得到了普及。

然而，传统的三层架构存在一个重大问题，那就是“领域（业务逻辑）会依赖于数据库或框架”。

例如，当业务逻辑层直接调用数据访问层（如ORM）时，数据库表结构的修改或ORM的变更就会波及到业务逻辑。也就是说，出现了这样一种矛盾：最重要且最不应该被修改的“业务规则”，反而依赖了最容易发生技术性变更的“基础设施”。

作为解决这个问题的方案，以下架构被相继提出：

六边形架构 (Ports and Adapters) - Alistair Cockburn
洋葱架构 - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

所有这些架构都具有相同的目的。那就是“关注点分离”。将软件划分为多个分层，使各层能够独立进行测试，并处于独立于外部代理（UI、数据库、框架）的状态。

Robert C. Martin将这些优秀的架构理念进行了整合，并总结为一个实用的规则，将其命名为“整洁架构”。

2. 整洁架构的目的与特性

采用整洁架构的系统具有以下特性：

独立于框架 (Independent of Frameworks): 架构不依赖于功能丰富的软件库的存在。这使得你可以将框架作为“工具”使用，而无需将系统强行塞入框架的约束中。
可测试 (Testable): 可以在没有UI、数据库、Web服务器或任何其他外部元素的情况下测试业务规则。
独立于UI (Independent of UI): UI可以在不改变系统其他部分的情况下轻松变更。例如，可以在不更改业务规则的情况下，将Web UI替换为控制台UI。
独立于数据库 (Independent of Database): 你可以将Oracle或SQL Server替换为Mongo、BigTable、CouchDB等。业务规则不与数据库绑定。
独立于任何外部代理 (Independent of any external agency): 实际上，你的业务规则对外部世界一无所知。

3. 整洁架构的四个分层 (Layers)

整洁架构通常用同心圆的图形来表示。越靠近中心，软件代表的策略层次就越高（抽象程度越高的业务规则）。越往外围，就越是机制（具体的细节）。

graph TD
subgraph "外部接口 (框架与驱动)"
A["Web"]
B["UI"]
C["数据库"]
D["外部API"]
end
subgraph "接口适配器"
E["控制器"]
F["网关"]
G["展示器"]
end
subgraph "应用业务规则 (用例)"
H["用例交互器"]
end
subgraph "企业业务规则 (实体)"
I["实体"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. 实体 (Entities)

实体封装了全企业范围的业务规则（Enterprise Business Rules）。实体可以是一个带有方法的对象，也可以是一组数据结构和函数。它们是可以在企业内多个不同应用中复用的、最通用和最高层的规则。即使你只编写了一个应用，实体也是该应用的业务对象。即使外部发生了变化（例如页面导航或安全机制的改变），实体也绝不会受到影响。

3.2. 用例 (Use Cases)

用例层包含了特定于应用的业务规则（Application Business Rules）。这一层封装并实现了系统的所有用例。用例协调流入和流出实体的数据流，并指示实体去实现系统的目标。这一层的变更绝不应该影响实体。同时，数据库、UI、框架等外部的变更也不会影响这一层。用例完全与这些关注点隔离开来。

3.3. 接口适配器 (Interface Adapters)

接口适配器层是一组适配器，负责将数据格式从对用例和实体最方便的形式，转换为对外部代理（如数据库和Web）最方便的形式。例如，Web世界中GUI的MVC（Model-View-Controller）架构元素就属于这里。控制器接收用户输入并传递给用例，展示器接收用例的输出并将其格式化为视图（UI）。此外，将数据转换为数据库（如SQL）能够理解的格式也是这一层的职责。该层以内的任何代码都不应该了解关于数据库的任何信息。

3.4. 框架与驱动 (Frameworks & Drivers)

最外层由数据库、Web框架等工具组成。在这里，通常除了与内层通信的“胶水代码（Glue Code）”之外，不会编写太多其他代码。这一层包含了所有的细节。Web是细节，数据库也是细节。为了将损害降到最低，我们将这些细节放在最外层。

4. 依赖规则 (The Dependency Rule)

为了使整洁架构成立，有一个最重要且绝对不能打破的规则。那就是“依赖规则 (The Dependency Rule)”。

源码的依赖关系必须只能指向同心圆的内侧（高层策略）。

属于内侧的任何代码都不应该知道外侧代码的任何信息。在外侧声明的名称（如函数、类、变量等）绝对不能在内侧被引用。同样，外侧使用的数据格式也不应该被内侧使用，特别是当该格式是由外侧的框架生成时更是如此。

graph LR
A["框架与驱动"] -->| 依赖 | B["接口适配器"]
B -->| 依赖 | C["用例"]
C -->| 依赖 | D["实体"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

用数学方式来表达，如果定义层级索引为 $L_i$，其中 $i=0$ 为实体（最内层），$i=3$ 为框架（最外层），当存在从某一层 $L_m$ 到 $L_n$ 的依赖时，必然满足以下不等式：

$$ m > n $$

也就是说，依赖关系向量 $\vec{D}$ 总是指向中心的。

5. 跨越边界：依赖反转原则 (DIP)

在试图遵守依赖规则时，很快就会面临一个重大问题：“如果用例需要从数据库获取数据，该怎么办？”

如果用例层（内侧）直接调用接口适配器层（外侧的Repository实现），依赖就会指向外侧，从而违反了依赖规则。

解决这个问题的方法是SOLID原则中的“D（Dependency Inversion Principle: 依赖反转原则）”。

依赖反转原则 (DIP) 的定义

高层模块不应该依赖低层模块。两者都应该依赖抽象。
抽象不应该依赖细节。细节应该依赖抽象。

为了实现这一点，我们在用例层定义一个接口（抽象），并在外层（接口适配器）实现该接口。用例层只依赖它自己定义的接口，而不依赖外层的具体实现。

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Depends on (依赖)"
UserRepositoryImpl ..|> UserRepository : "Implements (实现)"
note for UseCaseInteractor "内层 (用例)"
note for UserRepository "内层 (用例)"
note for UserRepositoryImpl "外层 (接口适配器)"

在上面的图中，运行时的控制流（Control Flow）是 UseCaseInteractor $\rightarrow$ UserRepositoryImpl。然而，源码的依赖关系（Source Code Dependency）却是 UserRepositoryImpl $\rightarrow$ UserRepository（内侧）。通过利用多态，我们成功地使源码的依赖关系指向了与控制流相反的方向。这就是它被称为“依赖反转”的原因。

6. 使用TypeScript的具体实现示例

在这里，我们使用TypeScript来展示一个整洁架构的简单实现示例（用户注册功能）。

6.1. 实体 (Entities)

这是位于最中心的业务规则。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // 实体特有的业务规则（例：名字长度检查等）
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. 用例 (Use Cases)

在用例层，我们定义了输入和输出的数据结构（DTO），以及用于反转依赖的仓储（Repository）接口。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// 由用例层定义的接口
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // 依赖于抽象（接口），而不依赖于具体实现。
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // 调用外层的数据库保存逻辑，但依赖方向指向内层（接口）
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. 接口适配器 (Interface Adapters)

我们创建了对数据库进行具体访问的处理（Repository的实现）以及处理HTTP请求的Controller。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// 假设为外层（Driver）的数据库客户端
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. 主组件 (依赖注入: DI)

在应用程序启动时，构建所有的依赖关系（组装）。这被称为组合根（Composition Root）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. 初始化驱动
const dbClient = new DatabaseClient(/* 连接信息 */);

// 2. 初始化适配器 (实例化具体类)
const userRepository = new PostgresUserRepository(dbClient);

// 3. 初始化用例 (将具体实现注入到接口中 = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. 初始化控制器
const userController = new UserController(registerUserUseCase);

// 路由
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

通过这种方式，最外层的“启动脚本”承担了肮脏的细节（实例化具体类），只向内层传递干净的接口结构，从而将业务逻辑与外部世界完全隔离开来。

7. 耦合度与内聚度的数学考量

在软件工程中，评价架构质量的指标有耦合度 (Coupling) 和 内聚度 (Cohesion)。

耦合度 $C$ 表示模块间依赖的强度。如果模块 $A$ 依赖于模块 $B$，设系统总依赖关系数为 $N_{dep}$，模块数为 $N_{mod}$，则表示复杂度的一个指标可如下表示：

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

在整洁架构中，通过应用DIP，我们将物理依赖的箭头指向了抽象。抽象（接口）的变更频率（不稳定性：$I$）被设计得非常低。

不稳定性 $I$ 可以通过以下公式计算（根据Robert C. Martin的定义）。

$C_e$ (Efferent Coupling): 向外的耦合（所依赖的数量）
$C_a$ (Afferent Coupling): 向内的耦合（依赖于自身的数量）

$$ I = \frac{C_e}{C_e + C_a} $$

如果 $I = 0$，则该组件是完全稳定的（不依赖任何其他组件，被其他组件所依赖）。
如果 $I = 1$，则该组件是完全不稳定的（不被其他组件所依赖，只依赖其他组件）。

在整洁架构的“实体层”中，$C_e = 0$（不依赖外部），因此 $I = 0$。也就是说，它是最稳定的层。相反，“UI层”或“数据库层”是 $C_a \approx 0$ 且 $C_e > 0$，因此 $I \approx 1$，它们成为容易被更改的层（不稳定的层）。

架构的重要原则 SDP（Stable Dependencies Principle: 稳定依赖原则）规定，“依赖必须指向更稳定的组件（$I$ 较小的组件）”。整洁架构的同心圆正是这个 SDP 的可视化，设计上使得依赖从外部（$I=1$）指向内部（$I=0$）。

8. 测试策略与整洁架构

整洁架构最大的优势之一就是易于测试。由于各层是分离的，可以独立编写针对各层的测试。

8.1. 实体的测试 (Unit Test)

因为它是没有任何外部依赖的纯粹逻辑，所以不需要数据库也不需要Mock。这是执行最快、最可靠的测试。

8.2. 用例的测试 (Unit Test with Mocks)

由于仓储等外部依赖全部被定义为接口，所以在测试时只需注入（DI）**用于测试的Mock或内存实现（Fake）**即可。无需启动实际的数据库。这使得能够快速测试业务逻辑的复杂分支和异常处理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 用例的测试示例 (假设使用Jest)
test('尝试使用已存在的邮箱地址注册时会报错', async () => {
 // 创建Fake仓储
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // 返回已存在的用户
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // 执行用例并断言错误
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. 适配器的测试 (Integration Test)

仓储的具体实现类实际上会连接到数据库以测试SQL是否正确。控制器的测试则验证接收HTTP请求并返回JSON的部分。在这里，不进行业务逻辑的详细验证，仅仅是为了确认“转换”和“通信”是否正确。

9. 整洁架构的缺点与采用时机

看起来万能的整洁架构，并不是强大的银弹。它存在以下缺点（权衡）：

初期的学习成本和开发成本增加：文件数量和接口（抽象）的数量会大幅增加。会有大量如DTO转换等“样板代码（Boilerplate Code）”。
对小型项目是大材小用：对于几天内做出的原型，或者几乎不会发生变更的一次性工具，采用这种架构通常是浪费成本。也不适合只有CRUD操作的简单API。

应采用的时机：

预计长期（数年以上）维护和运营的产品。
业务规则复杂且频繁进行需求变更的系统。
想要在大型开发团队中推进分工（前端、后端、基础设施等）的情况。
希望结合领域驱动设计（DDD: Domain-Driven Design）来对复杂的业务领域进行建模的情况。

10. 总结

整洁架构是一种设计思想，旨在保护被称为“业务规则”的系统核心，使其免受UI、数据库和框架等“细节”的影响。

其核心在于依赖规则和依赖反转原则 (DIP)。正确应用这些原则，可使软件对变化更加灵活，更容易测试，并在长时期内持续维持其价值。

重要的是，不要盲目模仿整洁架构的目录结构，而是要理解“为什么要这样划分”以及“依赖关系的箭头指向哪里”的本质，并根据自身项目的规模和复杂性适当地加以应用。

Reference: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” by Robert C. Martin