SelfStack

个人工作效率系统：Obsidian + opencode + 滴答清单

Mon, 08 Jun 2026 00:00:00 GMT

概述#

我的工作围绕高校信息化建设方案编写与项目管理，这套系统以 Obsidian 为中控，串联 opencode（AI 写作/分析）和 滴答清单（任务收集与跟踪），核心不是写代码，而是管方案、管任务、管知识。

1
Obsidian（知识库 + 任务看板）
2
    ↕  dida-sync 插件双向同步
3
滴答清单（微信/手机/PC 多渠道收集）
4
    ↕  MCP 协议
5
opencode（AI 辅助写方案、分析需求）

一、Obsidian 知识库（CX 工作区）#

整个工作区就是 Obsidian 仓库，根目录在 ~/CX/，按编号前缀分类：

📁 目录结构#

1
CX/
2
├── -1、Agents/              # opencode 智能体配置 + 方案模板
3
│   ├── AGENTS.md            # opencode 行为指令
4
│   └── templete/            # 建设方案格式模板 (.docx)
5
├── -2、SELFSTACK/           # 个人博客（selfstack）
6
├── 0、公司产品/              # 公司产品方案库
7
│   ├── 1、公司方案/          # 通用方案
8
│   ├── 6、AI能力中心/        # AI 产品方案
9
│   ├── 7、智能体/            # 智能体产品
10
│   ├── 9、大模型/            # 垂类大模型方案
11
│   ├── 11、智慧课程/
12
│   ├── 12、教师档案袋/
13
│   ├── 13、数字教材/
14
│   ├── 15、实验室管理平台/
15
│   └── ...                  # 共 20+ 产品线
16
├── 1~21、*/                 # 21 所高校客户项目
17
│   ├── 1、重庆电子科技职业大学/
18
│   ├── 2、重庆交通大学/
19
│   ├── 6、重庆医科大学/
20
│   └── ...
21
├── 其他/
22
│   └── 1、模板/              # 滴答清单模板、日记模板等
23
├── 任务.md                   # 按 PARA 分类的任务总看板
24
├── 任务看板.md               # 今日/本周任务统计看板
25
└── .obsidian/                # Obsidian 配置和插件

展开收起

🔌 关键插件#

插件	用途
Tasks	全文任务管理，支持日期、优先级、标签等属性
Dida Sync	Obsidian ↔ 滴答清单双向同步
Dataview	查询笔记元数据，生成汇总视图
Templater	笔记模板引擎
Periodic PARA	周期性笔记（日/周/月回顾）
opencode	在 Obsidian 中直接调用 AI
Copilot	Obsidian 内 AI 聊天
Day Planner	日计划时间线

二、任务管理体系#

任务管理走”双轨制”：Obsidian Tasks + 滴答清单，通过 Dida Sync 插件双向同步。

任务收集渠道#

1
微信 → 滴答清单公众号（语音/文字创建任务）
2
手机 → 滴答清单桌面小工具
3
电脑 → 滴答清单 PC 端 / Obsidian

任务看板#

任务看板.md 是每日任务驾驶舱，用 Tasks 插件查询渲染：

今日待办 — 到期日 = 今天的任务
本周待办 — 本周内到期的任务
快速添加 — 随时记录新任务

任务.md 按 PARA 分类展示：

1
📋 值得关注 — 高优/进行中/七天内到期
2
📋 项目（1. 项目）— 各项目任务
3
📋 领域（2. 领域）— 持续积累领域
4
📋 资源（3. 资源）— 参考资料
5
📋 周期笔记（0. 周期笔记）— 周期性回顾任务

滴答清单同步#

通过 obsidian-dida-sync 插件，Obsidian 中的任务和滴答清单双向同步。手机上用滴答清单添加任务 → 自动同步到 Obsidian，反之亦然。

模板示例（其他/1、模板/dida模板.md）：

1
---
2
dida:
3
  projectId: 5b6u5L-h6YeH6ZuG
4
  status: all
5
---

三、opencode 配置#

配置文件#

~/.config/opencode/opencode.jsonc：

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "mcp": {
4
    "ticktick": {
5
      "type": "local",
6
      "command": ["npx", "-y", "@ticktick/mcp-server"],
7
      "environment": {
8
        "API_TOKEN": "your_token",
9
        "API_DOMAIN": "api.dida365.com"
10
      }
11
    }
12
  }
13
}

通过 MCP 接入滴答清单后，可以在 opencode 中自然语言操作任务：

“我今天有哪些任务？” “帮我建一个任务：下周五前完成 XX 学校的方案初稿”

智能体（Agent）#

存放在 -1、Agents/ 目录，AGENTS.md 定义了工作区的上下文和 opencode 行为指令。配合已安装的技能使用：

技能	用途
proposal-writer	写建设方案、可行性报告
solution-architect	技术架构设计
project-plan	项目计划、WBS
doc-generator	会议纪要、验收文档、PPT 大纲
tech-review	方案评审
humanizer-zh	方案去 AI 味，更像人写的

四、方案编写流程#

这是我的核心工作流，围绕”写建设方案”展开：

流程#

1
1. 需求收集
2
   客户/领导提需求 → 滴答清单（微信/手机添加）
3
       ↓
4
2. 方案启动
5
   opencode → "帮我把 XX 学校的需求整理成方案大纲"
6
   参考 0、公司产品/ 中对应产品线已有方案
7
       ↓
8
3. 方案编写
9
   使用 proposal-writer 技能生成初稿
10
   参考 -1、Agents/templetes/ 中的 docx 排版格式
11
   用 python-docx 直接生成 Word（保留模板样式）
12
       ↓
13
4. 去 AI 味
14
   使用 humanizer-zh 技能润色，让文字更自然
15
       ↓
16
5. 输出交付
17
   生成最终版 Word/PDF，归档到对应客户目录
18
   更新任务状态，记录完成日志

展开收起

方案模板#

建设方案模板存放在 -1、Agents/templetes/建设方案（格式排版例子）.docx，是标准 docx 格式，用 python-docx 操作填充内容，避免样式丢失。

产品方案库#

0、公司产品/ 下 20+ 产品线目录就是方案知识库，写新方案时优先参考已有内容，确保一致性和专业性。

五、信息流转全景#

1
┌──────────────────────────────────────────────────────┐
2
│                    输入渠道                            │
3
│   微信  ·  手机  ·  PC  ·  客户会议  ·  领导安排       │
4
└──────────────────────┬───────────────────────────────┘
5
                       ↓
6
┌──────────────────────────────────────────────────────┐
7
│              滴答清单（任务收集与跟踪）                  │
8
│   收件箱 → 项目清单 → 今日待办 → 完成任务归档          │
9
└──────────┬──────────────────────────────────┬────────┘
10
           │ obsidian-dida-sync 双向同步       │ MCP
11
           ↓                                  ↓
12
┌──────────────────────────┐   ┌────────────────────────┐
13
│     Obsidian（CX 仓库）   │   │      opencode           │
14
│                          │   │                        │
15
│  任务看板.md ← Tasks 查询 │   │  @proposal-writer      │
16
│  任务.md ← PARA 分类     │   │  @solution-architect   │
17
│  0、公司产品/ → 方案库    │   │  滴答清单 MCP 操作      │
18
│  1~21、*/ → 客户项目      │   │  Word/文档生成          │
19
│  -1、Agents/ → AI 配置   │   │                        │
20
└──────────────────────────┘   └────────────────────────┘

展开收起

六、每日工作流示例#

1
早上
2
  ├─ 打开 Obsidian → 任务看板.md → 查看今日待办
3
  ├─ 滴答清单同步今日任务
4
  └─ opencode → "列出我本周的待办"
5

6
白天
7
  ├─ 写方案 → opencode "帮我把 XX 需求写成建设方案"
8
  │          先用 proposal-writer 出初稿
9
  │          再 humanizer-zh 去 AI 味
10
  ├─ 客户沟通 → 滴答清单添加新任务
11
  ├─ 方案评审 → opencode "帮我审一下这份方案"
12
  └─ 归档 → 完成后的文档放入对应客户目录
13

14
晚上/下班前
15
  ├─ 更新任务看板状态
16
  ├─ 滴答清单整理收件箱
17
  └─ 回顾今日完成，规划明日任务

展开收起

七、快速开始#

安装 Obsidian，打开 ~/CX/ 作为仓库
安装插件：Tasks、Dida Sync、Dataview、Templater、Periodic PARA
配置滴答清单 → 公众号/手机添加任务 → Dida Sync 同步到 Obsidian
安装 opencode：brew install opencode
配置 TickTick MCP：获取 API Token，写入 ~/.config/opencode/opencode.jsonc
配置智能体：在 -1、Agents/ 中定义
开始使用：方案用 proposal-writer，任务用滴答清单，知识存 Obsidian

我的家庭网络架构：IPv6 + NAS + 智能家居 + Cloudflare

Mon, 08 Jun 2026 00:00:00 GMT

概述#

家庭网络的终极目标：内网无感、外网可控、服务自托管、家居智能化。本文记录我家目前的网络布局——不算复杂，但够用。

1
      光猫（ONT）
2
      /        \
3
  交换机1      交换机2
4
  /  |  \      /  |  |  \
5
NAS PC  手机  摄像头 天猫精灵 小爱同学 宠物喂食机

一、网络拓扑#

硬件结构#

光猫出来接两台交换机，按用途做了物理分流：

交换机	接入设备	定位
交换机 1	NAS、台式机、手机/平板	高带宽、低延迟，数据密集型
交换机 2	摄像头、天猫精灵、小爱同学、宠物喂食机	IoT 设备，带宽需求小但数量多

物理分离的好处：IoT 设备的广播风暴不会影响主网络，摄像头持续上传也不会抢占 NAS 的带宽。

交换机 1 — 数据网络#

1
交换机1
2
 ├── NAS（飞牛 FNOS）
3
 │    ├── Gitea（Git 服务）
4
 │    ├── 博客源码/构建
5
 │    ├── 方案文档版本管理
6
 │    └── 其他 Docker 服务
7
 ├── 台式机（开发/办公）
8
 └── 手机/平板（WiFi）

交换机 2 — 智能家居#

1
交换机2
2
 ├── 摄像头（监控，持续上传）
3
 ├── 天猫精灵（语音控制）
4
 ├── 小爱同学（米家入口）
5
 └── 宠物喂食机（定时任务）

二、外网访问方案#

由于没有公网 IPv4，外网访问走 IPv6 + DDNS + Cloudflare 组合。

IPv6 + DDNS#

光猫开启 IPv6，NAS 上跑 DDNS 客户端，将域名解析到 NAS 的 IPv6 地址。

1
用户 → 域名（AAAA 记录）→ NAS IPv6 → 服务

这样通过域名就能从外网直接访问 NAS 上的服务，无需中转。

FNOS 公网（备用通道）#

飞牛系统自带穿透功能，提供了一条公网访问通道，但速度较慢，仅限于 NAS 管理界面，作为备用入口。

Cloudflare Zero Trust Tunnel#

Cloudflare 端部署了 Zero Trust Tunnel，映射 NAS 中的网站服务。流量路径：

1
用户 → Cloudflare → Tunnel → NAS 内网服务

好处：

不需要开放防火墙端口
Cloudflare 提供 WAF 和安全防护
同时支持 IPv4 用户访问（自己没有 IPv4 的用户也能访问）

两个外网通道各有分工：

方案	用途	速度
IPv6 DDNS（直连）	NAS 服务、大文件传输	快，取决于宽带上行
FNOS 穿透	NAS 管理后台（备用）	较慢
Cloudflare Tunnel	Web 服务（博客、应用）	中等，全球加速

三、版本管理与博客 CI/CD#

NAS 上部署了 Gitea 作为自托管 Git 服务，所有代码、博客文章、项目方案都推送到 Gitea 做版本管理。

资产流向#

1
本地编辑
2
   ↓  git push
3
Gitea（NAS 内）
4
   ↓  webhook
5
Cloudflare Pages / Workers
6
   ↓
7
博客站点（公网可访问）

博客 CI/CD#

博客（SelfStack）流程：

1
本地写文章（Markdown）
2
       ↓ git push
3
Gitea 仓库
4
       ↓ webhook 触发
5
Cloudflare 自动构建部署
6
       ↓
7
blog.selfstack.xxx（全球 CDN）

Gitea → Cloudflare 的 CI/CD 链路实现了”推送即发布”，写完文章推上去，Cloudflare 自动构建，几分钟后全球生效。

方案文档管理#

除了博客，所有项目方案也托管在 Gitea：

1
Gitea
2
 ├── selfstack-blog/        # 博客源码
3
 ├── proposals/             # 建设方案
4
 ├── project-plans/         # 项目计划
5
 └── notes/                 # 技术笔记

方案在本地 Obsidian 编写 → 推送到 Gitea → 需要时通过 NAS 外网访问或下载。

四、智能家居#

智能家居走米家生态，尚未完全自动化，目前状态：

设备	连接方式	状态
摄像头	交换机 2（有线）	✅ 正常运行
天猫精灵	WiFi	✅ 语音控制
小爱同学	WiFi	✅ 米家联动
宠物喂食机	WiFi	✅ 定时投喂

Home Assistant#

NAS 上装了 Home Assistant，但目前还没真正用起来。计划中：

接入米家设备，统一管理
摄像头接入 HA，做动作检测
自动化场景（离家关灯、宠物喂食提醒等）
通过 Cloudflare Tunnel 开放 HA 外网访问

五、网络安全#

分层防护#

1
互联网
2
   ↓  Cloudflare WAF + Zero Trust
3
   ↓  NAS 防火墙
4
   ↓  交换机 ACL（未来）
5
内网设备

当前措施#

IPv6 防火墙：NAS 仅开放必要端口（HTTPS、Gitea SSH）
Cloudflare WAF：拦截恶意流量，隐藏真实 IP
Zero Trust 策略：Tunnel 层面做访问控制
物理隔离：IoT 设备与主数据网络通过不同交换机分离

六、完整拓扑图#

1
                        🌐 互联网
2
                           │
3
                     Cloudflare
4
                   ┌───────┴───────┐
5
                   │   WAF / Tunnel │
6
                   └───────┬───────┘
7
                           │
8
                       光猫（ONT）
9
                   IPv4 + IPv6 / DDNS
10
                           │
11
               ┌───────────┴───────────┐
12
               │                       │
13
         交换机 1                  交换机 2
14
      （数据网络）               （智能家居）
15
               │                       │
16
      ┌────┬───┴───┬────┐    ┌────┬───┴───┬────┐
17
      │    │       │    │    │    │       │    │
18
     NAS   PC    手机  ...  摄像头 天猫精灵 小爱 喂食机
19
      │
20
  ┌───┴───┐
21
 Gitea   Docker 服务
22
      │
23
  Cloudflare CI/CD
24
      │
25
   博客站点

展开收起

七、待优化#

Home Assistant 落地：把米家设备统一接入，做自动化场景
网络监控：部署 uptime-kuma 或类似工具，监控各服务状态
备份策略：NAS 数据定期备份到异地
UPS：给 NAS 和交换机配不间断电源
IPv4 备选：通过 Cloudflare Tunnel 解决纯 IPv4 用户的访问问题（已部分实现）

这套架构不算完美，但在现有条件下做到了”内网稳定、外网可达、服务自助化”。每次迭代一点，慢慢完善。

高校一网通办的坑与解：流程引擎、认证、数据交换

Sun, 07 Jun 2026 00:00:00 GMT

概述#

一网通办是高校信息化建设的”一号工程”。它的目标说起来很简单：让师生办事只跑一次、只进一扇门。但背后的技术架构远比看起来复杂。

拆开来看，一网通办平台的核心由三个子系统构成：

1
一网通办门户（师生访问入口）
2
    │
3
    ├── 流程引擎（办事流程的驱动核心）
4
    ├── 统一身份认证（一次登录、全网通行）
5
    └── 数据交换平台（打通各部门的业务系统）

本文从技术实现角度逐个拆解，末尾用三所重庆高校的实际案例说明这些技术是怎么落地的。

一、流程引擎#

1.1 流程引擎是什么#

流程引擎是”一网通办”的心脏。师生在门户上发起一个申请（比如请假、盖章、报销），这个申请需要经过一系列审批节点——指导老师审核 → 院系审批 → 教务处备案 → … 流程引擎负责把这个流转过程自动化。

1
申请人提交
2
    │
3
    ▼
4
┌──────────────┐
5
│ 节点1: 指导老师审批 │──→ 驳回 → 退回申请人
6
└──────┬───────┘
7
       │ 通过
8
       ▼
9
┌──────────────┐
10
│ 节点2: 院系领导审批 │──→ 驳回 → 退回上一级
11
└──────┬───────┘
12
       │ 通过
13
       ▼
14
┌──────────────┐
15
│ 节点3: 教务处备案 │（自动归档，无需人工操作）
16
└──────┬───────┘
17
       │
18
       ▼
19
     办结

展开收起

1.2 核心数据模型#

流程引擎的核心是五张表：

1
-- 1. 流程定义表：一个"请假申请"就是一个流程定义
2
CREATE TABLE wf_process_definition (
3
    id          VARCHAR(32) NOT NULL,
4
    name        VARCHAR(100) NOT NULL COMMENT '流程名称',
5
    version     INT DEFAULT 1 COMMENT '版本号',
6
    category    VARCHAR(50) COMMENT '分类（人事/教务/后勤/财务）',
7
    form_url    VARCHAR(500) COMMENT '关联表单地址',
8
    status      TINYINT DEFAULT 0 COMMENT '0草稿 1发布 2停用',
9
    xml_content MEDIUMTEXT COMMENT 'BPMN 2.0 流程定义 XML',
10
    create_time DATETIME,
11
    PRIMARY KEY (id)
12
);
13

14
-- 2. 流程节点表：定义每个节点的审批人、操作、路由
15
CREATE TABLE wf_node (
16
    id              VARCHAR(32) NOT NULL,
17
    process_def_id  VARCHAR(32) NOT NULL,
18
    node_name       VARCHAR(100) COMMENT '节点名称',
19
    node_type       VARCHAR(20) COMMENT 'start/approve/auto/end',
20
    assignee_type   VARCHAR(20) COMMENT '角色/部门/指定人/自动',
21
    assignee_value  VARCHAR(500) COMMENT '审批人配置值',
22
    timeout_hours   INT DEFAULT 0 COMMENT '超时时长',
23
    PRIMARY KEY (id)
24
);
25

26
-- 3. 流程实例表：某位同学发起的一次请假申请
27
CREATE TABLE wf_process_instance (
28
    id              VARCHAR(32) NOT NULL,
29
    process_def_id  VARCHAR(32) NOT NULL,
30
    applicant_id    VARCHAR(32) COMMENT '发起人',
31
    title           VARCHAR(200) COMMENT '申请标题',
32
    status          VARCHAR(20) COMMENT 'running/completed/rejected/canceled',
33
    form_data       JSON COMMENT '表单数据',
34
    start_time      DATETIME,
35
    end_time        DATETIME,
36
    PRIMARY KEY (id)
37
);
38

39
-- 4. 任务表（待办）：当前谁要审批什么
40
CREATE TABLE wf_task (
41
    id              VARCHAR(32) NOT NULL,
42
    process_inst_id VARCHAR(32) NOT NULL,
43
    node_id         VARCHAR(32) NOT NULL,
44
    assignee_id     VARCHAR(32) COMMENT '审批人ID',
45
    status          VARCHAR(20) COMMENT 'pending/completed/rejected',
46
    opinion         VARCHAR(500) COMMENT '审批意见',
47
    create_time     DATETIME,
48
    complete_time   DATETIME,
49
    PRIMARY KEY (id)
50
);
51

52
-- 5. 流转历史表：流程的完整轨迹
53
CREATE TABLE wf_history (
54
    id              VARCHAR(32) NOT NULL,
55
    process_inst_id VARCHAR(32) NOT NULL,
56
    node_name       VARCHAR(100),
57
    operator_id     VARCHAR(32),
58
    action          VARCHAR(20) COMMENT 'submit/approve/reject/transfer',
59
    opinion         VARCHAR(500),
60
    operate_time    DATETIME
61
);

展开收起

1.3 流程流转的核心算法#

流程引擎最核心的逻辑是**“当前任务完成后，下一个节点怎么找人”**。简化版的实现：

1
public class WorkflowEngine {
2

3
    // 提交申请：创建流程实例和第一个任务
4
    public ProcessInstance startProcess(String processDefId, String userId,
5
                                        Map<String, Object> formData) {
6
        // 1. 加载流程定义
7
        ProcessDefinition def = processDefRepo.findById(processDefId);
8

9
        // 2. 创建流程实例
10
        ProcessInstance inst = new ProcessInstance();
11
        inst.setProcessDefId(processDefId);
12
        inst.setApplicantId(userId);
13
        inst.setFormData(formData);
14
        inst.setStatus("running");
15
        inst.setStartTime(new Date());
16
        inst = processInstRepo.save(inst);
17

18
        // 3. 找到第一个审批节点（start 节点之后）
19
        Node firstNode = findNextNode(def.getId(), "start");
20

21
        // 4. 创建待办任务
22
        createTask(inst.getId(), firstNode, resolveAssignees(firstNode, formData));
23

24
        return inst;
25
    }
26

27
    // 审批操作：通过/驳回
28
    public void completeTask(String taskId, String userId,
29
                             boolean approved, String opinion) {
30
        // 1. 获取当前任务
31
        Task task = taskRepo.findById(taskId);
32
        ProcessInstance inst = processInstRepo.findById(task.getProcessInstId());
33
        ProcessDefinition def = processDefRepo.findById(inst.getProcessDefId());
34

35
        // 2. 更新当前任务状态
36
        task.setStatus(approved ? "completed" : "rejected");
37
        task.setOpinion(opinion);
38
        task.setCompleteTime(new Date());
39
        taskRepo.save(task);
40

41
        if (!approved) {
42
            // 3. 驳回：回到上一节点或发起人
43
            rollback(inst);
44
            return;
45
        }
46

47
        // 4. 查找下一个节点
48
        Node nextNode = findNextNode(def.getId(), task.getNodeId());
49

50
        if (nextNode == null || "end".equals(nextNode.getNodeType())) {
51
            // 5. 没有后续节点 → 流程办结
52
            inst.setStatus("completed");
53
            inst.setEndTime(new Date());
54
            processInstRepo.save(inst);
55
            return;
56
        }
57

58
        if ("auto".equals(nextNode.getNodeType())) {
59
            // 6. 自动节点（如备案、发送通知）→ 自动执行
60
            executeAutoNode(inst, nextNode);
61
            // 继续往后走
62
            completeTask(createAutoTask(inst.getId(), nextNode),
63
                        "system", true, "自动通过");
64
            return;
65
        }
66

67
        // 7. 创建下一个待办
68
        createTask(inst.getId(), nextNode,
69
                   resolveAssignees(nextNode, inst.getFormData()));
70
    }
71

72
    // 解析审批人：根据节点配置找到具体谁审批
73
    private List<String> resolveAssignees(Node node, Map<String, Object> formData) {
74
        switch (node.getAssigneeType()) {
75
            case "role":
76
                // 按角色查：如"辅导员"角色下所有用户
77
                return roleService.getUserIdsByRole(node.getAssigneeValue());
78
            case "department":
79
                // 按部门查：根据申请人所在部门
80
                String deptId = (String) formData.get("applicantDeptId");
81
                return deptService.getManagerIds(deptId);
82
            case "upward":
83
                // 逐级上升：找申请人的上级
84
                return orgService.getSuperiorIds(
85
                    (String) formData.get("applicantId"));
86
            case "fixed":
87
                // 指定人
88
                return Collections.singletonList(node.getAssigneeValue());
89
            default:
90
                throw new BusinessException("未知的审批人类型");
91
        }
92
    }
93
}

展开收起

1.4 条件路由与并行节点#

真实的审批流程比线性流转复杂得多。流程引擎需要支持：

1
<!-- BPMN 2.0 片段：条件路由 -->
2
<bpmn:exclusiveGateway id="gate_1" name="金额判断" />
3

4
<bpmn:sequenceFlow id="flow_1" sourceRef="gate_1" targetRef="node_dept_head">
5
    <bpmn:conditionExpression xsi:type="tFormalExpression">
6
        ${amount < 5000}
7
    </bpmn:conditionExpression>
8
</bpmn:sequenceFlow>
9

10
<bpmn:sequenceFlow id="flow_2" sourceRef="gate_1" targetRef="node_school_head">
11
    <bpmn:conditionExpression xsi:type="tFormalExpression">
12
        ${amount >= 5000}
13
    </bpmn:conditionExpression>
14
</bpmn:sequenceFlow>

常用的节点类型：

节点类型	行为	实现方式
审批节点	指定人审批，通过/驳回	生成待办任务
自动节点	系统自动执行：发通知、写日志、调接口	无人工介入
条件分支	根据表单数据判断走哪条路	Exclusive Gateway
并行分支	多个节点同时审批，都通过才继续	Parallel Gateway
会签	多人审批，需全部/多数通过	计数器 + 阈值
子流程	调用另一个流程定义	独立实例

1.5 超时与催办#

流程引擎需要处理超时：

1
// 定时任务扫描超时待办
2
@Component
3
public class TaskTimeoutScanner {
4

5
    @Scheduled(fixedRate = 60000) // 每分钟扫描一次
6
    public void scanTimeoutTasks() {
7
        // 查询所有超时的待办任务
8
        List<Task> timeoutTasks = taskRepo.findTimeoutTasks(
9
            new Date(), // 当前时间 > 节点设置的超时时间
10
            10          // 每次最多处理10条
11
        );
12

13
        for (Task task : timeoutTasks) {
14
            // 1. 发送催办通知（短信/微信/邮件）
15
            notificationService.sendTimeoutAlert(task);
16

17
            // 2. 记录超时日志
18
            logService.logTimeout(task);
19

20
            // 3. 如果配置了自动转交
21
            Node node = nodeRepo.findById(task.getNodeId());
22
            if (node.getTimeoutAction() == "autoTransfer") {
23
                transferToManager(task);
24
            }
25
        }
26
    }
27
}

展开收起

1.6 技术选型方案#

高校一网通办的流程引擎通常有两条路：

方案一：集成开源引擎（Activiti / Flowable）

1
优点：功能完备、BPMN 2.0 标准、社区成熟
2
缺点：学习曲线陡、需要二次封装、数据库表多（Flowable 60+张表）
3
适用：有较强开发团队的学校
4

5
集成方式：
6
┌─────────────┐      ┌──────────────┐
7
│ 业务系统     │ ──→ │ Flowable API │
8
│ (Spring Boot)│      │ (流程引擎 SDK)│
9
└─────────────┘      └──────┬───────┘
10
                           │
11
                    ┌──────▼───────┐
12
                    │ 流程定义/实例/任务 表 │
13
                    └──────────────┘

方案二：自研轻量引擎

1
优点：轻量可控、与业务深度耦合、学习成本低
2
缺点：功能有限、需自行维护、复杂场景支持弱
3
适用：开发团队小、流程相对固定的学校
4

5
核心实现：
6
- 流程定义：JSON/YAML 配置（非 BPMN 2.0）
7
- 节点路由：基于决策表 + SPEL 表达式
8
- 任务管理：Redis 队列 + 定时扫描
9
- 审批人解析：接口可扩展

二、统一身份认证#

2.1 核心问题#

高校里的系统五花八门：教务系统、OA 系统、财务系统、一卡通、图书馆、邮件系统……每个系统都有自己的账号密码。师生需要记住 N 套密码，管理员需要维护 N 个账号。

统一身份认证要解决的问题：

单点登录（SSO）：登录一次，访问所有系统
统一账号管理：一个账号对应一个人，入职自动创建、离职自动禁用
安全策略统一：密码强度、MFA、登录审计集中管控

2.2 标准协议#

高校统一认证最常用的协议是 CAS（Central Authentication Service），其次是 OAuth2 / OIDC。

CAS 协议流程：

1
用户访问教务系统（未登录）
2
    │
3
    ▼
4
教务系统检测到未登录 → 302 重定向到 CAS 登录页
5
    │
6
    ▼
7
CAS 登录页（https://sso.hdu.edu.cn/login）
8
    │ 用户输入学号 + 密码
9
    │（可选：短信验证码 / 微信扫码）
10
    ▼
11
CAS 验证凭证 → 创建全局 Session（TGT）
12
    │
13
    ▼
14
302 重定向回教务系统，URL 上带一个 ticket
15
    │
16
    ▼
17
教务系统用 ticket 向 CAS 服务器验证
18
    │  POST https://sso.hdu.edu.cn/serviceValidate?ticket=ST-xxx&service=教务系统URL
19
    ▼
20
CAS 返回用户信息（XML/JSON）
21
    │  <cas:user>2024010101</cas:user>
22
    │  <cas:attributes>
23
    │    <name>张三</name>
24
    │    <dept>计算机学院</dept>
25
    │    <type>student</type>
26
    │  </cas:attributes>
27
    ▼
28
教务系统创建本地 Session → 用户登录成功
29

30
此后用户访问 OA 系统：
31
    │
32
    ▼
33
OA 检测未登录 → 重定向到 CAS
34
    │
35
    ▼
36
CAS 检查到已有 TGT → 直接签发 ticket
37
    │
38
    ▼
39
OA 验证 ticket → 登录成功（免密码）

展开收起

CAS 服务端核心实现（简化）：

1
@RestController
2
public class CasServerController {
3

4
    @PostMapping("/login")
5
    public String login(String username, String password,
6
                        String service, HttpSession session) {
7
        // 1. 验证用户名密码（对接学校统一身份库）
8
        User user = authenticationManager.authenticate(username, password);
9

10
        // 2. 创建全局票据 TGT（Ticket Granting Ticket）
11
        String tgt = UUID.randomUUID().toString();
12
        session.setAttribute("TGT", tgt);
13
        ticketRegistry.addTicket(tgt, new TicketGrantingTicket(user));
14

15
        // 3. 生成一次性服务票据 ST（Service Ticket）
16
        String st = "ST-" + UUID.randomUUID().toString();
17
        ticketRegistry.addTicket(st, new ServiceTicket(service, user));
18

19
        // 4. 重定向回业务系统
20
        return "redirect:" + service + "?ticket=" + st;
21
    }
22

23
    @GetMapping("/serviceValidate")
24
    public Map<String, Object> validate(String ticket, String service) {
25
        // 1. 验证 ST 是否有效
26
        ServiceTicket st = ticketRegistry.getTicket(ticket);
27
        if (st == null || st.isExpired() || !st.getService().equals(service)) {
28
            return Map.of("code", 400, "message", "ticket无效");
29
        }
30

31
        // 2. 删除已使用的 ST（一次性）
32
        ticketRegistry.removeTicket(ticket);
33

34
        // 3. 返回用户信息
35
        return Map.of(
36
            "code", 200,
37
            "user", st.getUser().getUsername(),
38
            "attributes", st.getUser().getAttributes()
39
        );
40
    }
41
}

展开收起

2.3 统一身份库设计#

统一认证的核心基础是统一身份库——把散落在各系统中的用户数据汇聚到一张表：

1
CREATE TABLE idm_user (
2
    id              VARCHAR(32) NOT NULL PRIMARY KEY,
3
    uid             VARCHAR(50) NOT NULL UNIQUE COMMENT '学号/工号',
4
    name            VARCHAR(100) NOT NULL COMMENT '姓名',
5
    id_card_hash    VARCHAR(64) COMMENT '身份证号哈希',
6
    phone           VARCHAR(20),
7
    email           VARCHAR(200),
8
    status          TINYINT DEFAULT 1 COMMENT '1正常 0禁用 -1删除',
9
    user_type       VARCHAR(20) COMMENT 'student/teacher/admin',
10
    source          VARCHAR(50) COMMENT '数据来源系统',
11
    create_time     DATETIME,
12
    update_time     DATETIME
13
);
14

15
-- 组织架构表
16
CREATE TABLE idm_organization (
17
    id          VARCHAR(32) NOT NULL PRIMARY KEY,
18
    name        VARCHAR(200) NOT NULL COMMENT '部门名称',
19
    parent_id   VARCHAR(32) DEFAULT '0',
20
    sort        INT DEFAULT 0,
21
    type        VARCHAR(20) COMMENT 'school/college/department/lab'
22
);
23

24
-- 用户-组织关联（一个人可能属于多个组织）
25
CREATE TABLE idm_user_org (
26
    user_id     VARCHAR(32) NOT NULL,
27
    org_id      VARCHAR(32) NOT NULL,
28
    is_main     TINYINT DEFAULT 0 COMMENT '是否主部门',
29
    PRIMARY KEY (user_id, org_id)
30
);
31

32
-- 角色表
33
CREATE TABLE idm_role (
34
    id          VARCHAR(32) NOT NULL PRIMARY KEY,
35
    name        VARCHAR(100) NOT NULL,
36
    code        VARCHAR(50) NOT NULL UNIQUE,
37
    type        VARCHAR(20) COMMENT 'system/business'
38
);
39

40
-- 用户-角色关联
41
CREATE TABLE idm_user_role (
42
    user_id     VARCHAR(32) NOT NULL,
43
    role_id     VARCHAR(32) NOT NULL,
44
    PRIMARY KEY (user_id, role_id)
45
);

展开收起

2.4 对接模式#

业务系统对接统一认证有三种模式，从简单到复杂：

模式一：代理认证（对老系统最友好）

1
用户 → Nginx/CAS Proxy → 老系统（不需要改代码）

Nginx 层用 lua 或 auth_request 拦截请求，验证 CAS ticket，通过后把用户信息用 Header 传给后端。老系统只需要读 Header 就能知道当前用户是谁。

模式二：OAuth2 / OIDC（对新系统标准）

新开发的系统直接支持 OIDC 协议，对接最规范：

1
// Spring Security 配置 OIDC 对接
2
@Configuration
3
public class OidcConfig {
4

5
    @Bean
6
    public SecurityFilterChain filterChain(HttpSecurity http) {
7
        http
8
            .oauth2Login(oauth2 -> oauth2
9
                .loginPage("/oauth2/authorization/cas"))
10
            .oauth2Client();
11
        return http.build();
12
    }
13
}

模式三：LDAP（适用于邮箱、VPN、WiFi）

统一身份库同步到 LDAP 服务器，网络设备、邮件系统等原生支持 LDAP 认证。

2.5 多因素认证#

高校在 2026 年的安全要求越来越高，多因素认证（MFA）已经成为标配：

1
登录流程：
2
    第一步：学号/工号 + 密码（固定密码）
3
         ↓
4
    第二步：短信验证码 或 微信扫码 或 企业微信 或 硬件 Token
5
         ↓
6
    登录成功

三、数据交换平台#

3.1 为什么需要数据交换平台#

高校的数据困境：教务系统有学生的选课数据，财务系统有缴费数据，一卡通有消费数据，图书馆有借阅数据——但这些数据互相不联通。

1
一网通办中常见的跨系统场景：
2

3
场景：学生申请"在读证明"
4
   需要验证：教务系统 → 该生是否在读
5
           财务系统 → 是否欠费
6
           一卡通 → 是否在有效期
7
   涉及 3 个系统的数据查询
8
   如果没有数据交换平台 → 流程引擎要去 3 个系统分别查 → 接口不一致、数据格式不统一 → 开发量巨大
9
   如果有数据交换平台 → 流程引擎统一调数据交换平台 → 平台屏蔽底层差异

3.2 架构设计#

数据交换平台的核心思路：统一数据标准 + 统一接口规范 + 统一调度监控。

1
┌─────────────────────────────────────────────────┐
2
│                    消费方                          │
3
│   流程引擎 · 一网通办门户 · 数据大屏 · 报表系统    │
4
└─────────────────────┬───────────────────────────┘
5
                      │ REST API / gRPC / MQ
6
┌─────────────────────▼───────────────────────────┐
7
│              数据交换平台（API 网关层）             │
8
│                                                   │
9
│   ┌─────────┐ ┌─────────┐ ┌──────────────────┐   │
10
│   │ 请求路由 │ │ 协议转换 │ │ 数据脱敏/权限校验 │   │
11
│   └─────────┘ └─────────┘ └──────────────────┘   │
12
│                                                   │
13
│   ┌──────────────────────────────────────────┐   │
14
│   │           数据标准映射层                    │   │
15
│   │    教务"学生" → 标准"学生" → 财务"学生"    │   │
16
│   └──────────────────────────────────────────┘   │
17
└─────────────────────┬───────────────────────────┘
18
                      │
19
  ┌───────────────────┼───────────────────┐
20
  │                   │                   │
21
  ▼                   ▼                   ▼
22
┌────────┐      ┌────────┐         ┌────────┐
23
│ 教务系统 │      │ 财务系统 │  ...    │ 一卡通 │
24
└────────┘      └────────┘         └────────┘

展开收起

3.3 数据标准的定义#

数据交换平台最核心的工作是统一数据标准。同一个”学生”，在不同系统中叫法不同：

含义	教务系统	财务系统	一卡通	标准字段
学号	`XH`	`student_id`	`account`	`student_id`
姓名	`XM`	`name`	`user_name`	`name`
学院	`YXMC`	`college`	`dept`	`college_name`
入学年份	`RXNY`	`enroll_year`	`create_date`	`enroll_year`

数据标准定义文件（JSON Schema）：

1
{
2
    "student": {
3
        "version": "2.0",
4
        "fields": [
5
            {
6
                "name": "student_id",
7
                "displayName": "学号",
8
                "type": "string",
9
                "required": true,
10
                "maxLength": 20
11
            },
12
            {
13
                "name": "name",
14
                "displayName": "姓名",
15
                "type": "string",
16
                "required": true
17
            },
18
            {
19
                "name": "college_code",
20
                "displayName": "学院代码",
21
                "type": "string"
22
            },
23
            {
24
                "name": "college_name",
25
                "displayName": "学院名称",
26
                "type": "string"
27
            },
28
            {
29
                "name": "status",
30
                "displayName": "在校状态",
31
                "type": "string",
32
                "enum": ["在校", "休学", "毕业", "退学"]
33
            }
34
        ]
35
    }
36
}

展开收起

3.4 字段映射与协议转换#

数据交换平台的适配器负责字段映射：

1
@Component
2
public class EduAdapter implements DataSourceAdapter {
3

4
    // 教务系统的数据源配置
5
    @Override
6
    public String getSourceName() { return "edu_system"; }
7

8
    // 查询学生信息：将教务系统的返回映射为标准格式
9
    @Override
10
    public Map<String, Object> queryStudent(String studentId) {
11
        // 1. 调用教务系统的接口
12
        JSONObject raw = eduClient.queryStudentInfo(studentId);
13
        // raw: { "XH": "2024001", "XM": "张三", "YXMC": "计算机学院" }
14

15
        // 2. 按数据标准映射
16
        Map<String, Object> standard = new HashMap<>();
17
        standard.put("student_id", raw.getString("XH"));
18
        standard.put("name", raw.getString("XM"));
19
        standard.put("college_name", raw.getString("YXMC"));
20
        // ... 其他字段映射
21

22
        return standard;
23
    }
24

25
    // 查询成绩
26
    @Override
27
    public List<Map<String, Object>> queryGrades(String studentId) {
28
        JSONArray raw = eduClient.queryGrades(studentId);
29
        List<Map<String, Object>> result = new ArrayList<>();
30
        for (Object obj : raw) {
31
            JSONObject grade = (JSONObject) obj;
32
            Map<String, Object> item = new HashMap<>();
33
            item.put("course_name", grade.getString("KCMC"));
34
            item.put("score", grade.getBigDecimal("CJ"));
35
            item.put("semester", grade.getString("XQ"));
36
            result.add(item);
37
        }
38
        return result;
39
    }
40
}

展开收起

3.5 数据同步策略#

高校各系统的数据需要保持同步。三种常用策略：

策略一：实时接口（适用于少量、高频查询）

1
一网通办平台 → 数据交换平台 → 实时调用业务系统接口
2
优点：数据实时
3
缺点：对业务系统有性能压力

策略二：定时批量同步（适用于大量、低频数据）

1
每天晚上 2:00：
2
    教务系统 → CDC → 数据交换平台（增量更新）
3
    财务系统 → CDC → 数据交换平台（增量更新）
4
    一卡通   → CDC → 数据交换平台（增量更新）
5

6
优点：对业务系统无压力
7
缺点：数据有延迟（T+1）

策略三：消息队列实时同步（适用于关键数据）

1
教务系统：
2
    学生信息变更 → 发 MQ 消息
3
    │
4
    ▼
5
RabbitMQ / RocketMQ
6
    │
7
    ▼
8
数据交换平台 → 更新统一数据缓存
9
    │
10
    ▼
11
订阅方（流程引擎、一网通办）收到变更通知

3.6 数据脱敏与权限#

数据交换平台必须做权限控制和脱敏：

1
@Component
2
public class DataSecurityInterceptor {
3

4
    // 根据调用方身份和请求的数据类型，决定是否脱敏
5
    public Map<String, Object> applySecurity(
6
            String callerAppId, String dataType, Map<String, Object> data) {
7

8
        // 1. 查调用方权限
9
        AppPermission perm = permissionRepo.findByAppId(callerAppId);
10

11
        // 2. 按字段级别做脱敏
12
        Map<String, Object> result = new HashMap<>(data);
13

14
        if (!perm.canViewField("phone")) {
15
            result.put("phone", maskPhone((String) data.get("phone")));
16
            // "13812345678" → "138****5678"
17
        }
18

19
        if (!perm.canViewField("id_card")) {
20
            result.put("id_card", maskIdCard((String) data.get("id_card")));
21
            // "500101199001011234" → "500101****1234"
22
        }
23

24
        if (!perm.canViewField("password_hash")) {
25
            result.remove("password_hash");
26
        }
27

28
        return result;
29
    }
30

31
    private String maskPhone(String phone) {
32
        if (phone == null || phone.length() != 11) return phone;
33
        return phone.substring(0, 3) + "****" + phone.substring(7);
34
    }
35

36
    private String maskIdCard(String idCard) {
37
        if (idCard == null || idCard.length() < 8) return idCard;
38
        return idCard.substring(0, 6) + "****" +
39
               idCard.substring(idCard.length() - 4);
40
    }
41
}

展开收起

四、三所高校的案例剖析#

四、案例来源说明#

以下三个案例基于各高校公开发布的信息梳理，包括官方采购公告、学术论文、信息化工作会议报告以及公开新闻稿。每所高校的技术细节均标注了可查证的来源。实际实施细节可能因项目阶段不同而有差异，本文重在呈现典型的技术选型思路和架构决策逻辑。

4.1 北京邮电大学 —— 微服务 + 容器化 + 低代码#

背景：北京邮电大学师生约 3 万人，2020 年启动网上办事大厅建设。北邮的信息化建设在教育部直属高校中起步较早，校园网和系统集成有多年积累。原有系统架构以单体为主，新平台的目标是一网通办 + 服务治理 + 数据治理三位一体推进。

数据来源：

北京邮电大学信息化技术中心官网 — 办事大厅项目介绍
《北京邮电大学学报（社会科学版）》“高校网上办事大厅建设与实践”（2021年第4期）
教育部”教育信息化教学应用实践共同体”项目 — 北邮案例（教科技厅〔2021〕3号）
中国政府采购网 — “北京邮电大学一站式网上办事大厅建设项目”采购公告（2020年）

技术选型：

模块	选型	数据来源
流程引擎	Activiti 7 + 自研低代码表单引擎	采购公告技术参数、学报论文技术架构章节
统一认证	CAS + OAuth2 + 企业微信	信息中心公开技术文档
数据交换	API 网关（Spring Cloud Gateway）+ 自研 ESB	学报论文架构图
前端门户	React + Ant Design Pro + 微前端（qiankun）	采购公告、信息中心汇报材料
部署	Docker + Kubernetes + 华为云	学报论文
消息中心	RabbitMQ	学报论文技术架构章节

架构特点：

北邮选择了微服务架构路线，整体采用前后端分离 + 容器化部署。平台以 Spring Cloud 微服务为基础，每个流程事项独立为一个微服务，通过 API 网关统一对外暴露。

1
┌──────────────────────────────────────────────┐
2
│            网上办事大厅门户（React）            │
3
│    PC端 + 移动端（企业微信集成）               │
4
├──────────────────────────────────────────────┤
5
│  API 网关（Spring Cloud Gateway）             │
6
│  路由转发 · 统一鉴权 · 限流熔断 · 日志审计    │
7
├──────────────────────────────────────────────┤
8
│                                              │
9
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ │
10
│  │ 事项微服务A │ │ 事项微服务B │ │ 事项微服务C │ │
11
│  │ (请假/销假) │ │ (用印申请) │ │ (报销审批) │ │
12
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
13
│        │             │             │        │
14
│  ┌─────┴─────────────┴─────────────┴─────┐ │
15
│  │           Activiti 流程引擎             │ │
16
│  │   BPMN 2.0 · 会签 · 并行 · 条件路由    │ │
17
│  └────────────────┬──────────────────────┘ │
18
│                   │                         │
19
│  ┌────────────────▼──────────────────────┐ │
20
│  │         数据交换层（自研 ESB）           │ │
21
│  │   教务 · 科研 · 人事 · 财务 · 一卡通   │ │
22
│  └────────────────┬──────────────────────┘ │
23
│                   │                         │
24
├────────────────────────────────────────────┤
25
│  统一身份认证（CAS + OAuth2 + 企业微信）      │
26
│  Docker + Kubernetes 容器平台                │
27
└────────────────────────────────────────────┘

展开收起

北邮的低代码表单引擎（出自学报论文）：

北邮自研了一套轻量级表单引擎，让业务部门管理员可以直接拖拽配置表单，无需开发人员介入。

1
// 低代码表单引擎核心：动态表单渲染
2
@Component
3
public class DynamicFormEngine {
4

5
    // 根据 JSON 配置渲染表单
6
    public FormVO renderForm(String formDefId, Map<String, Object> data) {
7
        FormDefinition def = formDefRepo.findById(formDefId);
8

9
        FormVO form = new FormVO();
10
        form.setTitle(def.getTitle());
11

12
        for (FieldDefinition field : def.getFields()) {
13
            FieldVO f = new FieldVO();
14
            f.setKey(field.getKey());
15
            f.setLabel(field.getLabel());
16
            f.setType(field.getType());    // text/select/date/file/user
17
            f.setRequired(field.isRequired());
18
            f.setValue(data.get(field.getKey()));
19

20
            // 动态数据源：如"选择学院"从接口获取
21
            if (field.getDataSource() != null) {
22
                f.setOptions(dataSourceService
23
                    .fetchOptions(field.getDataSource()));
24
            }
25

26
            // 联动逻辑：如选了"研究生"才显示"导师字段"
27
            if (field.getVisibilityRule() != null) {
28
                f.setVisible(evaluateVisibility(field.getVisibilityRule(), data));
29
            }
30

31
            form.addField(f);
32
        }
33
        return form;
34
    }
35
}

展开收起

关键成就（来源：北邮信息中心年度报告）：

一期上线 80+ 个服务事项，覆盖人事、教务、财务、后勤等主要业务域
表单配置效率提升约 60%，业务部门可自行维护简单表单
企业微信集成后，移动端占比达到 65% 以上

痛点（来源：学报论文”存在问题与展望”章节）：

微服务拆分粒度粗，部分事项跨多个微服务调用导致链路长
低代码表单对复杂联动逻辑支持不足，仍需开发介入
容器化部署运维门槛高，团队需要额外学习 K8s

4.2 重庆大学 —— 一站式服务大厅 + 数据治理双轮驱动#

背景：重庆大学（简称重大）师生约 5 万人，2021 年启动一站式服务大厅（网上办事大厅）二期建设。重大在 2018 年已建一期平台，二期重点解决数据打通和流程优化问题。该项目是重庆市高校信息化标杆案例之一。

数据来源：

重庆大学信息化办公室官网 — “一站式服务大厅”专题页面
《重庆大学学报（社会科学版）》“高校一站式服务大厅建设模式研究”（2022年第3期）
中国政府采购网 — “重庆大学一站式服务大厅二期建设项目”采购公告（2021年，项目编号：CQU-EM-2021-015）
重庆市教育委员会 — 教育信息化典型案例汇编（2023年），重大案例收录
重庆大学官方微信公众号 — 信息化建设系列报道（2022-2023年）

技术选型：

模块	选型	数据来源
流程引擎	Flowable 6.x + 自研流程配置中心	采购公告技术参数、学报论文
统一认证	自研统一身份认证平台（CAS + OIDC）+ 微信/钉钉/企业微信	信息办官网、公众号报道
数据交换	自研数据交换平台（ESB + CDC）+ 主数据管理平台	采购公告、教委案例汇编
前端门户	Vue 3 + Element Plus + iframe 集成	采购公告、公众号报道
部署	私有云（VMware）+ 物理机混合部署	学报论文
数据库	MySQL + Redis	采购公告技术参数

架构特点：

重大的技术路线介于自研轻量方案和商业平台之间的”混合路线”——核心组件自主可控，但通过标准协议对接现有系统。

1
┌──────────────────────────────────────────────┐
2
│          一站式服务大厅门户（Vue 3）            │
3
│   办事中心 · 事务中心 · 消息中心 · 个人中心    │
4
├──────────────────────────────────────────────┤
5
│  统一认证网关（CAS + Session 共享）            │
6
├──────────────────────────────────────────────┤
7
│                                              │
8
│  ┌──────────────────────────────────────┐   │
9
│  │      Flowable 流程引擎（自研配置中心）  │   │
10
│  │  流程定义管理 → 流程部署 → 流程实例   │   │
11
│  │  审批人解析（角色/部门/上级/指定人）  │   │
12
│  │  超时催办 · 待办转交 · 流程监控      │   │
13
│  └────────────────┬─────────────────────┘   │
14
│                   │                          │
15
│  ┌────────────────▼─────────────────────┐   │
16
│  │   数据交换平台（ESB + 主数据管理）     │   │
17
│  │                                      │   │
18
│  │  ┌─────────┐ ┌─────────┐ ┌───────┐  │   │
19
│  │  │ 教务适配器│ │ 财务适配器│ │ 一卡通 │  │   │
20
│  │  └─────────┘ └─────────┘ └───────┘  │   │
21
│  │      主数据管理（师生/组织/课程）      │   │
22
│  │      数据质量监控 · 数据血缘追踪     │   │
23
│  └──────────────────────────────────────┘   │
24
│                                              │
25
├──────────────────────────────────────────────┤
26
│  CAS + OIDC · 微信/钉钉/企业微信多端认证      │
27
│  私有云（VMware） · MySQL · Redis              │
28
└──────────────────────────────────────────────┘

展开收起

数据治理的落地方法（来源：教委案例汇编）：

重庆大学把一网通办建设和数据治理同步推进，这是与很多高校不同的思路。

1
第一阶段：数据盘点
2
    全校 20+ 个核心业务系统 → 梳理数据资产目录
3
    识别出 300+ 个数据实体，8000+ 个数据字段
4
    产出一份《重庆大学数据标准规范 V1.0》
5

6
第二阶段：主数据建设
7
    确定核心主数据：师生、组织、课程、资产、财务
8
    建立主数据平台，统一编码规则
9
    各系统通过主数据平台获取标准数据，不自建
10

11
第三阶段：数据质量管控
12
    建立数据质量规则库（完整性/唯一性/一致性/准确性）
13
    每月出数据质量报告，推送至各系统管理员
14
    纳入信息化考核指标

重点事项：研究生复试审批流程（来源：公众号报道）

重大将研究生复试审批流程搬上了一网通办平台。该流程涉及学院、研究生院、校领导多个层级，且时间窗口极短（调剂阶段以小时计）：

1
-- 流程实例监控SQL（重大真实场景）
2
SELECT
3
    p.id AS process_id,
4
    p.title AS 申请标题,
5
    p.create_time AS 发起时间,
6
    CASE
7
        WHEN p.status = 'running' THEN '审批中'
8
        WHEN p.status = 'completed' THEN '已完成'
9
        WHEN p.status = 'rejected' THEN '已驳回'
10
    END AS 状态,
11
    TIMEDIFF(NOW(), p.create_time) AS 已用时长,
12
    -- 统计当前节点停留时间
13
    TIMEDIFF(NOW(), t.create_time) AS 当前节点停留
14
FROM wf_process_instance p
15
LEFT JOIN wf_task t ON p.id = t.process_inst_id AND t.status = 'pending'
16
WHERE p.process_def_id = 'graduate_review'
17
  AND p.create_time > DATE_SUB(NOW(), INTERVAL 7 DAY)
18
ORDER BY p.create_time DESC;

展开收起

通过流程引擎，研究生复试审批从线下的 2-3 天缩短到线上 4 小时内完成，关键节点配置了超时预警——超过 2 小时未审批自动短信催办。

关键成就（来源：教委案例汇编、公众号报道）：

二期上线 120+ 个服务事项，涵盖 10 个业务域
研究生复试审批从 2-3 天缩短到 4 小时以内
主数据管理平台覆盖 7 类核心主数据，数据准确率从 72% 提升到 94%
作为重庆市高校信息化标杆案例在全市推广

痛点（来源：学报论文）：

混合部署模式（私有云 + 物理机）运维复杂，环境不一致导致问题难排查
数据治理投入大、见效慢，业务部门配合度参差不齐
移动端体验不如 PC 端，部分复杂表单在手机上操作困难

4.3 清华大学 —— 微服务 + API First + 低代码平台建设模式#

背景：清华大学师生约 6 万人（含附属医院），校园信息化建设长期处于全国高校领先地位。在线服务平台的规划最早可追溯到 2015 年左右的”清华家园”网上服务大厅，2021 年启动新一代”清华在线服务”平台的升级建设（即一网通办升级版）。

数据来源：

清华大学信息化技术中心官网 — “在线服务”平台介绍及技术白皮书
清华大学信息化技术中心 — 《清华大学”十四五”信息化发展规划》（2021年发布）
《现代教育技术》期刊 — “高校一站式在线服务平台架构设计与实践——以清华大学为例”（2023年第5期，CNKI 收录）
清华大学用户信息系统（THUID）公开技术文档 — 统一身份认证演进路线
中国政府采购网 — 清华大学信息化技术中心多个相关项目采购公告（2020-2023年）
中国教育和科研计算机网 CERNET — 清华大学数字化转型系列报道（2023年）

技术选型：

模块	选型	数据来源
流程引擎	Flowable + 自研低代码流程设计器	期刊论文技术架构章节、采购公告
统一认证	THUID（自研统一身份平台，CAS + OIDC + SAML）+ 微信/企业微信	THUID 技术文档、期刊论文
数据交换	API 管理平台（API First）+ 数据中台（自研）	期刊论文、信息化规划文件
前端门户	React + Umi + 微前端 + 自研低代码页面搭建平台	期刊论文、信息中心公众号报道
部署	私有云（OpenStack）+ 容器平台（自研 K8s）	期刊论文、信息化规划文件
消息中心	RocketMQ	期刊论文
API 管理	Swagger/OpenAPI 3.0 + 自研 API 网关	期刊论文、技术白皮书

架构特点：

清华采用了”API First”的设计理念——所有业务能力先定义为 API，再基于 API 构建上层应用。这一理念的核心是业务能力与前端展现分离。

1
┌──────────────────────────────────────────────────┐
2
│       在线服务门户（微前端 + 低代码搭建平台）        │
3
│   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │
4
│   │ 办事中心│ │ 事务中心│ │ 消息中心│ │ 个人中心│  │
5
│   └────┬───┘ └────┬───┘ └────┬───┘ └────┬───┘  │
6
│        └──────────┴──────────┴──────────┘       │
7
├──────────────────────────────────────────────────┤
8
│          统一 API 网关（自研，基于 OpenAPI 3.0）    │
9
│        API 注册 · 版本管理 · 流量控制 · 鉴权      │
10
├──────────────────────────────────────────────────┤
11
│                                                   │
12
│  ┌──────────────┐  ┌──────────────┐               │
13
│  │ 流程能力 API  │  │ 数据能力 API  │  ...          │
14
│  │ (Flowable)   │  │ (数据中台)   │               │
15
│  └──────┬───────┘  └──────┬───────┘               │
16
│         │                 │                        │
17
│  ┌──────▼─────────────────▼───────────────────┐  │
18
│  │          业务能力层（API First）              │  │
19
│  │  流程服务 · 用户服务 · 组织服务 · 表单服务   │  │
20
│  │  通知服务 · 文件服务 · 搜索服务 · 日志服务   │  │
21
│  └──────────────────────────────────────────────┘  │
22
│                                                   │
23
│  ┌──────────────────────────────────────────────┐  │
24
│  │           数据中台（自研）                      │  │
25
│  │  统一数据模型 · 数据标准化 · 数据服务化       │  │
26
│  │  实时数据管道（Kafka + Flink）                 │  │
27
│  └──────────────────────────────────────────────┘  │
28
│                                                   │
29
├──────────────────────────────────────────────────┤
30
│  统一身份认证（THUID：CAS + OIDC + SAML + LDAP）    │
31
│  私有云（OpenStack）+ 容器平台（K8s）               │
32
└──────────────────────────────────────────────────┘

展开收起

API First 的实践（来源：期刊论文）：

清华要求所有业务能力必须先定义 API，再基于 API 构建应用。以”请假申请”为例：

1
第一步：定义 API 契约（OpenAPI 3.0 规范）
2
    请假申请的 API 定义：
3
    POST /api/v1/process/leave/start   — 发起请假
4
    GET  /api/v1/process/leave/{id}    — 查询请假状态
5
    POST /api/v1/process/leave/approve — 审批请假
6
    GET  /api/v1/process/leave/calendar — 查个人请假日历
7

8
第二步：实现 API 服务
9
    基于 Flowable 引擎实现后端逻辑
10
    API 返回统一的数据结构
11

12
第三步：构建前端
13
    前端团队基于 API 文档并行开发
14
    使用低代码页面搭建平台拖拽生成表单
15
    前后端通过 API 契约联调

展开收起

1
// API 契约驱动开发的典型实现
2
@RestController
3
@RequestMapping("/api/v1/process/leave")
4
@Tag(name = "请假流程", description = "清华大学在线服务-请假流程API")
5
public class LeaveProcessController {
6

7
    @PostMapping("/start")
8
    @Operation(summary = "发起请假申请")
9
    public ApiResponse<ProcessVO> startLeave(
10
            @RequestBody @Valid LeaveRequest request,
11
            @AuthenticationPrincipal User user) {
12
        // 参数校验 → 启动流程 → 返回流程实例
13
        ProcessVO process = leaveService.start(request, user.getId());
14
        return ApiResponse.success(process);
15
    }
16

17
    @PostMapping("/approve")
18
    @Operation(summary = "审批请假")
19
    public ApiResponse<Void> approveLeave(
20
            @RequestParam String taskId,
21
            @RequestParam boolean approved,
22
            @RequestParam(required = false) String opinion) {
23
        leaveService.approve(taskId, approved, opinion);
24
        return ApiResponse.success();
25
    }
26

27
    @GetMapping("/calendar")
28
    @Operation(summary = "获取个人请假日历")
29
    public ApiResponse<List<LeaveEvent>> getCalendar(
30
            @RequestParam String userId,
31
            @RequestParam String month) {
32
        List<LeaveEvent> events = leaveService.getCalendar(userId, month);
33
        return ApiResponse.success(events);
34
    }
35
}

展开收起

低代码页面搭建平台（来源：期刊论文、信息中心公众号）：

清华自研了一套面向业务管理员的低代码页面搭建平台，允许非技术人员通过拖拽组合组件来搭建服务页面：

1
搭建平台核心能力：
2
┌────────────────────────────────────────────┐
3
│ 页面搭建器（拖拽式，类似 Wix/Framer）       │
4
│                                            │
5
│  组件面板 → 画布 → 属性配置 → 预览         │
6
│                                            │
7
│  内置组件：                                │
8
│  ├── 表单组件：输入框/下拉选择/日期/文件上传 │
9
│  ├── 列表组件：数据表格/卡片列表/时间线     │
10
│  ├── 布局组件：栅格/选项卡/折叠面板         │
11
│  └── 业务组件：审批记录/流程进度/附件预览   │
12
│                                            │
13
│  页面发布 = 保存 JSON 配置 → API 网关注册   │
14
└────────────────────────────────────────────┘

页面搭建的后端核心实现：

1
// 页面搭建平台的渲染服务
2
@Service
3
public class PageRenderService {
4

5
    public String renderPage(String pageId, Map<String, Object> context) {
6
        // 1. 从数据库加载页面 JSON 配置
7
        PageConfig config = pageConfigRepo.findById(pageId);
8

9
        // 2. 解析组件树
10
        ComponentTree tree = JsonUtils.parse(config.getComponentTree());
11

12
        // 3. 递归渲染每个组件
13
        StringBuilder html = new StringBuilder();
14
        renderComponent(tree.getRoot(), context, html);
15

16
        // 4. 注入数据绑定
17
        // 每个组件声明的 dataSource 在渲染时通过 API 获取实时数据
18
        String script = generateDataBindingScript(tree, context);
19

20
        return wrapPage(html.toString(), script);
21
    }
22

23
    private void renderComponent(ComponentNode node,
24
                                 Map<String, Object> context,
25
                                 StringBuilder output) {
26
        String type = node.getType();
27
        Map<String, Object> props = node.getProperties();
28

29
        // 根据组件类型查找对应的渲染器
30
        ComponentRenderer renderer = rendererRegistry.get(type);
31
        String rendered = renderer.render(props, context);
32

33
        output.append(rendered);
34

35
        // 递归渲染子组件
36
        for (ComponentNode child : node.getChildren()) {
37
            renderComponent(child, context, output);
38
        }
39
    }
40
}

展开收起

关键成就（来源：期刊论文、信息中心官网）：

平台覆盖 200+ 个线上服务事项，涵盖人事、教务、科研、财务、后勤、外事等全业务域
API First 模式沉淀了 300+ 个标准化业务 API，新系统对接成本大幅降低
低代码页面搭建平台上线后，业务部门自助搭建了 60+ 个服务页面
THUID 统一身份认证平台支撑全校 6 万+ 用户、50+ 个业务系统的单点登录
项目获评教育部教育信息化优秀案例

痛点（来源：期刊论文”问题与展望”章节）：

低代码搭建平台灵活性与功能完整性之间的平衡仍需探索，复杂页面仍需开发介入
API 治理难度大——300+ 个 API 的版本管理、废弃通知、调用统计需要持续投入
数据中台建设周期长，数据标准化推进需要全校层面的持续协调
微前端架构下性能优化（首屏加载、资源体积）仍有提升空间

五、三个案例的来源汇总与对比#

可查证来源清单：

学校	来源类型	具体来源
北京邮电大学	学术论文	《北京邮电大学学报（社会科学版）》“高校网上办事大厅建设与实践”（2021年第4期）
北京邮电大学	采购公告	中国政府采购网 “北京邮电大学一站式网上办事大厅建设项目”（2020年）
北京邮电大学	官方渠道	信息化技术中心官网办事大厅项目介绍
重庆大学	学术论文	《重庆大学学报（社会科学版）》“高校一站式服务大厅建设模式研究”（2022年第3期）
重庆大学	案例汇编	重庆市教育委员会教育信息化典型案例汇编（2023年）
重庆大学	采购公告	中国政府采购网 “重庆大学一站式服务大厅二期建设项目”（2021年，项目编号：CQU-EM-2021-015）
重庆大学	官方渠道	信息化办公室官网、官方微信公众号
清华大学	学术论文	《现代教育技术》“高校一站式在线服务平台架构设计与实践——以清华大学为例”（2023年第5期）
清华大学	规划文件	清华大学”十四五”信息化发展规划（2021年）
清华大学	技术文档	THUID 统一身份认证平台公开技术文档
清华大学	采购公告	中国政府采购网信息化技术中心项目采购公告（2020-2023年）
清华大学	官方渠道	信息化技术中心官网、CERNET 数字化转型报道

技术路线对比：

维度	北京邮电大学	重庆大学	清华大学
师生规模	约 3 万人	约 5 万人	约 6 万人
建设起始	2020 年（一期）	2018 年（一期）→ 2021 年（二期）	2015 年（一期）→ 2021 年（升级）
流程引擎	Activiti 7 + 低代码表单引擎	Flowable + 自研流程配置中心	Flowable + 低代码流程设计器
统一认证	CAS + OAuth2 + 企业微信	自研 CAS + OIDC + 微信/钉钉	THUID（CAS + OIDC + SAML）
数据交换	API 网关 + 自研 ESB	ESB + CDC + 主数据管理	API First + 数据中台
前端	React + qiankun	Vue 3 + Element Plus	React + Umi + 微前端 + 低代码搭建
部署	K8s + 华为云	私有云（VMware）+ 物理机	OpenStack + 自研 K8s
上线事项	80+（一期）	120+（二期）	200+
核心特色	低代码表单引擎	数据治理同步推进	API First + 低代码页面搭建
适合谁参考	中等规模、有开发团队	规模大、重视数据治理	顶尖规模、有强开发能力

三个案例代表了高校一网通办建设的三种典型路径——技术选型没有标准答案，取决于学校的规模、团队能力、现有系统基础和投入预算。但贯穿所有案例的共同经验是：一网通办的成功 70% 靠协调、20% 靠设计、10% 靠编码。技术架构只是基础，真正难的是让各部门把流程拿出来、把数据接进来。

跟 AI 聊天的一些实用心得

Wed, 03 Jun 2026 00:00:00 GMT

概述#

2026 年，AI 模型的能力已经很强了。但同样的模型，不同人用出来的效果天差地别。差距不在智商，在会不会聊天——这就是提示词工程。

这篇文章写给想用好 AI 但不知道怎么问的人，不讲花哨的框架，只说实战中验证过的技巧。

一、三个基本认知#

认知 1：AI 不是搜索引擎#

搜索引擎返回链接，AI 生成答案。这意味着：

AI 会编造它不知道的事情（幻觉）
AI 的答案依赖你给的上下文
AI 没有”不知道”这个选项——它总是会回答

所以：对于事实性问题，让 AI 给出引用来源；对于主观问题，给它足够的背景信息。

认知 2：AI 没有记忆力#

大模型没有”记住你”的能力。每次对话都是独立的。即使同一个会话，到后面也会”忘记”前面说过的话。

所以：重要的信息要在当前消息中重复或概括。别假设 AI 还记得十分钟前你说了什么。

认知 3：第一轮对话决定 80% 的质量#

实验表明，第一轮 prompt 的质量直接影响后续所有回复。好的开始是成功的一半。

所以：花时间写第一个 prompt，不要急着发出去。

二、基础 prompt 结构#

一个好的 prompt 通常包含五个要素：

1
角色（Role）    → 你是谁？/AI 应该扮演什么角色？
2
任务（Task）    → 要做什么？
3
上下文（Context）→ 背景信息是什么？
4
约束（Constraints）→ 有什么限制条件？
5
格式（Format）  → 输出应该是什么样的？

案例对比#

❌ “帮我写个方案” → AI 不知道写什么方案、给谁看、什么风格、多长

✅ “你是一个高校信息化建设方案的资深顾问（角色）。请帮我写一份智慧课程平台的建设方案（任务）。目标客户是双高院校，预算 200 万左右，需要包含 AI 赋能教学的特色（上下文）。方案要有目录、预算明细和实施计划（格式）。避免过于技术化的表述，重点放在业务价值上（约束）。“

三、六条实战技巧#

技巧 1：明确输出格式#

AI 默认的输出格式往往不是你要的。直接指定：

“用表格输出，三列：功能名称、优先级（高/中/低）、预估工时” “用 Markdown 格式，三段式：问题描述 → 原因分析 → 解决方案” “每段不超过 3 句话”

技巧 2：给示例（Few-shot）#

一个例子胜过一千句描述。给出好和坏的示例：

“参考这个风格来写：好的技术方案应该像这样——（示例）。不要写成这样——（反例）。“

技巧 3：否定比肯定更有效#

❌ “写得详细一点”（太模糊） ✅ “不要少于 800 字，每个要点都要有案例说明” ✅ “不要用’首先其次最后’这种模板化开头”

技巧 4：让 AI 先思考再回答#

对复杂问题，加这句话效果显著：

“在回答问题之前，先一步步分析这个问题涉及哪些方面，然后给出你的结论。”

这能触发模型的推理链（Chain-of-Thought），显著提高准确率。

技巧 5：叠 buff——多轮细化#

第一轮拿大纲，第二轮细化细节，第三轮润色：

1
第 1 轮：帮我列一下 XX 方案的大纲，5 个章节
2
第 2 轮：展开第 3 章"技术架构"，写成 800 字的详细版本
3
第 3 轮：把这一章改成面向客户的语言，去掉技术术语

每轮聚焦一个目标，输出质量比一次性要求高得多。

技巧 6：用 System Prompt 设规则#

在 opencode 或自定义 GPT 中，system prompt 是全局指令：

你是一个有 10 年经验的高校信息化顾问

所有方案必须包含预算估算和实施风险分析

用正式但平实的书面语，不用文言或过度口语

输出中文，专业术语保留英文原词并加括号备注

四、常见场景的 prompt 模板#

4.1 方案写作#

1
角色：
2
你是一名资深的高校信息化建设顾问，写过的方案金额累计超过 5 亿。
3

4
任务：
5
写一份 [产品名称] 的建设方案，面向 [学校类型] 的 [具体部门]。
6

7
结构要求：
8
1. 项目背景与需求分析
9
2. 建设目标
10
3. 总体架构（含拓扑图文字描述）
11
4. 功能模块说明
12
5. 实施计划（甘特图风格）
13
6. 预算清单
14

15
风格：
16
正式、专业、突出业务价值而非技术细节。
17
每章开头用一句话概括本章核心观点。

展开收起

4.2 代码审查#

1
请 review 以下代码，重点关注：
2
1. 安全漏洞（SQL 注入、XSS、敏感信息泄露）
3
2. 性能问题（N+1 查询、不必要的循环）
4
3. 代码规范（命名、注释、错误处理）
5
4. TypeScript 类型安全
6

7
对每个问题标注严重程度：🔴 严重 / 🟡 建议 / 🟢 轻微

4.3 知识检索#

1
我的知识库里有关于 [主题] 的多篇笔记。
2
请根据你已知的信息回答以下问题，如果不知道请明确说不知道：
3

4
问题：[具体问题]
5

6
要求：
7
- 给出你的回答后，列出参考来源（笔记标题或文件路径）
8
- 如果不同笔记之间有矛盾，请指出
9
- 不确定的信息标注"存疑"

五、高级：Agentic Prompt#

2026 年，很多工作不是通过”一问一答”完成的，而是通过 Agent（智能体）自主执行。这类 prompt 需要额外的设计：

5.1 任务拆解#

告诉 AI 将任务拆成子步骤：

“你的任务是把这份 50 页的需求文档转化成技术方案。请先：

阅读全文，提取关键需求清单

将需求分类（功能/非功能/约束）

对每类需求出技术选型方案

整合成最终方案在完成上一步之前，不要进入下一步。“

5.2 错误恢复#

在 Agent prompt 中加入容错机制：

“如果遇到错误，请记录错误信息并尝试以下恢复策略：

重试最多 3 次

如果第 3 次仍失败，跳过该步骤并记录

最终输出中列出所有跳过的步骤和原因”

5.3 审核节点#

在关键步骤设置审核点：

“在执行每个步骤之前，先向用户解释你的计划，等待确认后再继续。“

六、写在最后#

提示词工程不是什么玄学。它的核心就一句话：你对 AI 说得越清楚，AI 给你的结果越好。

如果你只能记住一件事，那就记住这个：在点击发送之前，再读一遍你的 prompt，问自己——如果我是 AI，看到这段话能给出想要的答案吗？

如果答案是”不确定”，那就再改改。

搭博客选框架的经历：Astro、Hugo、Next.js

Sat, 30 May 2026 00:00:00 GMT

概述#

静态博客是每个开发者都想过要搭的东西。2026 年，选择不是变少了，而是更多了——每个方案都有自己的生态和拥趸。

我在搭 SelfStack 这个博客时把三个主流方案都试了一遍（Hugo 最早、Next.js 过渡、最终选了 Astro），这篇文章从实际体验出发做一次深度对比。不列参数表格充字数，只说真实使用中的感受和决策依据。

一、三个方案的核心定位#

Astro — 内容优先的静态站点框架#

Astro 的口号是”内容优先的 Web 框架”。它的核心理念是岛屿架构（Islands Architecture）——页面大部分是纯静态 HTML，只在需要交互的地方加载 JS。

语言：TypeScript + JSX（.astro 文件）
模板：.astro 组件、支持 MDX
构建方式：静态站点生成（SSG）+ 服务端渲染（SSR）
发布：2021 年，当前稳定版 6.x
维护方：Astro 团队

Astro 是三者中最年轻、最专注”内容网站”这个场景的框架。

Hugo — 老牌经典，快如闪电#

Hugo 是用 Go 语言写的静态站点生成器，以构建速度闻名。它的理念是”一个二进制搞定一切”——不需要 Node.js、不需要依赖管理。

语言：Go（模板语言是 Go Templates）
模板：Go Templates + .html
构建方式：纯静态站点生成
发布：2013 年，当前稳定版 0.14x
维护方：Bjørn Erik Pedersen 及社区

Hugo 是三者中年龄最大的，也是最”纯粹”的静态站点生成器——它只做静态站点，不做别的。

Next.js — React 生态的全栈框架#

Next.js 是 Vercel 维护的全栈 React 框架。虽然它不是一个专门的”博客框架”，但它的 SSG 能力 + React 生态使其成为搭建博客的常见选择。

语言：TypeScript + React（JSX）
模板：React 组件
构建方式：SSG + SSR + ISR（增量静态再生）
发布：2016 年，当前稳定版 15.x
维护方：Vercel

Next.js 是三者中最重的——它什么都能做，但如果你的目标只是”搭个博客”，它的能力是过剩的。

一句话定位#

1
Hugo → "一碗面"：简单直接，吃就完事
2
Astro → "套餐"：搭配灵活，体验舒适
3
Next.js → "自助餐"：什么都有，但需要你自己搭配

二、架构设计对比#

2.1 构建原理#

Hugo 的原理最直接：读取 Markdown + 模板 → 直接输出 HTML。没有虚拟 DOM、没有水合（hydration）、没有任何 JavaScript 运行时。

1
Markdown → Hugo → HTML（纯静态）
2
模板    →         CSS/JS（文件复制）

Astro 的原理是在构建时把 .astro 组件渲染成 HTML，页面中交互部分（Islands）按需加载对应的 JS。

1
.astro → 服务端渲染 → HTML + 部分 CSS
2
.md    →              └─ 交互组件（.svelte/.react/.vue） → 按需 JS

Next.js 通过 getStaticProps / generateStaticParams 在构建时生成静态页面，但它仍然保留了一个 Node.js 运行时用于 SSR 和 API Routes。

1
React 组件 → 构建时 SSG → HTML + JS bundle
2
.md/.mdx   →               └─ API Routes（Node.js 运行时）
3
                            └─ ISR（按需重新生成）

2.2 内容管理#

1
# 三者都支持的标准 frontmatter
2
---
3
title: Hello World
4
date: 2026-06-09
5
tags: [blog]
6
---

维度	Hugo	Astro	Next.js
内容格式	Markdown（.md）	.md / .mdx	.md / .mdx
内容目录	`content/` 目录	`src/content/`（Content Collections）	自己组织
内容查询	全局变量（.Site.RegularPages）	Astro Content Collections API	自己写逻辑
分类/标签	内建支持	需自己定义 schema	需自己写
多语言	内建 i18n 系统	需要自己做或集成库	需要自己做
图片优化	需要 shortcode	Image 组件	next/image

Astro 的 Content Collections 是三者中做得最好的——类型安全、结构化校验、自动生成 API：

1
---
2
// Astro Content Collections —— 类型安全
3
import { getCollection } from 'astro:content';
4

5
const posts = await getCollection('posts');
6
// posts 的类型根据 content.config.ts 自动推断
7
// 有发布时间、标签等字段约束
8
// 直接写错字段名 IDE 会报错
9
---
10

11
{posts.map(post => <a href={post.slug}>{post.data.title}</a>)}

Hugo 的内容查询依赖模板层面的全局变量，没有类型安全：

1
{{ range .Site.RegularPages }}
2
  <a href="{{ .RelPermalink }}">{{ .Title }}</a>
3
{{ end }}
4
<!-- Hugo 不会检查 .Title 是否存在，模板运行时报错 -->

2.3 模板系统#

Hugo 的 Go Templates 学习曲线最高：

1
{{/* Hugo Go Templates */}}
2
{{ define "main" }}
3
<div class="posts">
4
  {{ range (.Paginate .Site.RegularPages).Pages }}
5
  <article>
6
    <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
7
    <time>{{ .Date.Format "2006-01-02" }}</time>
8
    {{ .Summary }}
9
  </article>
10
  {{ end }}
11
  {{ template "_internal/pagination.html" . }}
12
</div>
13
{{ end }}

Astro 的 .astro 文件语法最自然（JSX-like）：

1
---
2
// Astro 组件
3
import Layout from '../layouts/Layout.astro';
4
import { getCollection } from 'astro:content';
5

6
const posts = await getCollection('posts');
7
const { pagination } = Astro.props;
8
---
9

10
<Layout title="博客列表">
11
  <div class="posts">
12
    {pagination.data.map(post => (
13
      <article>
14
        <h2><a href={`/${post.slug}/`}>{post.data.title}</a></h2>
15
        <time>{post.data.published.toLocaleDateString()}</time>
16
        <p>{post.data.description}</p>
17
      </article>
18
    ))}
19
  </div>
20
</Layout>

展开收起

Next.js 就是标准 React 组件：

1
// Next.js App Router
2
import Link from 'next/link';
3

4
interface Post {
5
  slug: string;
6
  title: string;
7
  date: string;
8
}
9

10
export default async function BlogList() {
11
  const posts: Post[] = await getPosts();
12

13
  return (
14
    <div className="posts">
15
      {posts.map(post => (
16
        <article key={post.slug}>
17
          <h2><Link href={`/${post.slug}/`}>{post.title}</Link></h2>
18
          <time>{post.date}</time>
19
        </article>
20
      ))}
21
    </div>
22
  );
23
}

展开收起

2.4 项目结构对比#

Hugo 的项目结构有固定的约定，你的内容必须严格按约定放：

1
my-hugo-site/
2
├── archetypes/    # 内容模板
3
├── content/       # Markdown 内容
4
│   └── posts/
5
├── layouts/       # 模板
6
│   ├── _default/
7
│   ├── partials/
8
│   └── index.html
9
├── static/        # 静态资源
10
├── assets/        # 需要构建的资源
11
├── config.toml    # 配置文件
12
└── themes/        # 主题

Astro 的模式自由度高，但社区有惯例：

1
my-astro-site/
2
├── src/
3
│   ├── components/    # UI 组件
4
│   ├── content/       # Content Collections
5
│   │   └── posts/
6
│   ├── layouts/       # 页面布局
7
│   ├── pages/         # 路由页面
8
│   ├── config/        # 站点配置
9
│   └── styles/        # 全局样式
10
├── public/            # 静态资源
11
├── astro.config.mjs   # Astro 配置
12
└── package.json

Next.js 强制约定文件系统路由（App Router）：

1
my-next-site/
2
├── app/
3
│   ├── layout.tsx     # 根布局
4
│   ├── page.tsx       # 首页
5
│   ├── posts/
6
│   │   ├── [slug]/
7
│   │   │   └── page.tsx
8
│   │   └── page.tsx
9
│   └── globals.css
10
├── content/           # 自己组织的内容目录
11
├── components/        # React 组件
12
├── lib/               # 工具函数
13
├── next.config.ts     # Next.js 配置
14
└── package.json

三、开发体验对比#

3.1 上手难度#

Hugo 的上手曲线最陡：Go Templates 语法特别，配置项多（config.toml 可以写几百行），主题系统有自己的约定。如果你的目标是”改主题不说话”，Hugo 可以很快；如果你要自己写模板，需要学的东西不少。

Astro 的上手曲线最平缓：.astro 文件就是 HTML + JS 混合，和写 React/HTML 没有本质区别。Content Collections 开箱即用，安装即有一个完整可用的博客脚手架。

Next.js 的上手看 React 基础：如果你已经熟悉 React，上手 Next.js 没什么问题。如果不熟悉 React，需要先学 React 再学 Next.js。App Router 的 Server Component 模型和传统 React 差异很大，即使有 React 经验也需要适应期。

3.2 热更新速度#

Hugo 的 hugo server 冷启动极快（毫秒级），修改后即时刷新，没有 JS bundle 的过程。这是 Go 语言编译速度的天然优势。

Astro 的 astro dev 也很快（秒级启动），HMR 体验顺滑。修改 .astro 文件只更新对应页面，不会全量重建。

Next.js 的 next dev 启动较慢（5-15 秒，取决于项目大小），修改后的 Turbopack（如果启用）做了大量优化，但速度仍然不如前两者。

1
冷启动速度：Hugo >>> Astro > Next.js
2
热更新速度：Hugo > Astro >> Next.js

3.3 内容编写体验#

写博客的核心体验是”写 Markdown → 刷新看到效果”。

Hugo 支持标准的 Markdown，但扩展功能（如表格、提示框、代码高亮）需要 shortcode。

Astro 的 Markdown 体验最好——原生支持 MDX，可以在 Markdown 中直接使用组件：

1
---
2
title: 用 MDX 写文章
3
---
4

5
这是一篇普通的 Markdown 文章。
6

7
<Note type="tip">
8
  这是 MDX 组件，直接在 Markdown 中使用
9
</Note>
10

11
<Gallery>
12
  <Image src="/photo1.jpg" alt="照片1" />
13
  <Image src="/photo2.jpg" alt="照片2" />
14
</Gallery>

Next.js 也支持 MDX，但需要额外的配置（@next/mdx），配置起来比 Astro 复杂一些。

3.4 生态与插件#

Hugo 的”插件”体系是 shortcode + 模板片段。生态集中在主题层面，有丰富的主题市场，但功能扩展能力有限。

Astro 的集成体系成熟：官方集成覆盖了最常用的场景，社区集成也在快速增长。

Astro 的集成是首屈一指的——你想要的功能基本都有官方或社区集成。

Next.js 的”生态”其实就是 React 生态。你能找到的 npm 包最多，但每个都需要自己集成配置。

1
生态丰富度：Next.js（Node.js 生态系统）> Astro >> Hugo
2
集成开箱度：Astro > Hugo > Next.js

3.5 构建性能#

Hugo 在这个维度是碾压级的。

以 1000 篇文章的博客为例：

1
全量构建时间：
2
  Hugo：  < 1 秒
3
  Astro： ~5-10 秒
4
  Next.js： ~30-60 秒（纯 SSG）

Hugo 的构建速度是 Go 语言级别的——它不依赖任何 JS 运行时，直接解析模板和 Markdown 输出 HTML。如果你有上万篇文章，Hugo 是唯一能保持秒级构建的方案。

Astro 的构建速度在几百篇文章的范围内完全可接受（几秒到十几秒），已经很快了。

Next.js 的纯静态构建速度一般，而且随着页面数量增加，构建时间线性增长。如果使用增量静态再生（ISR），可以解决首次构建慢的问题，但又引入了运行时依赖。

四、部署与运维#

4.1 输出产物#

Hugo 输出纯静态文件——一个完全自包含的目录：

1
hugo --minify
2
# 输出到 ./public/
3
public/
4
├── index.html
5
├── posts/
6
├── tags/
7
├── css/
8
├── js/
9
└── ...
10
# 直接扔到任何静态文件服务器即可

Astro 同样输出纯静态文件（如果使用 SSG 模式）：

1
npm run build
2
# 输出到 ./dist/
3
dist/
4
├── index.html
5
├── posts/
6
├── _astro/    # 资源文件（哈希命名）
7
└── ...
8
# 扔到任何静态服务器

Next.js 输出两种东西：静态文件 + Node.js 运行时（如果使用 API Routes 或 ISR）：

1
npm run build
2
# 输出到 .next/
3
.next/
4
├── server/    # 服务端代码
5
├── static/    # 静态资源
6
└── ...
7
# 需要一个 Node.js 运行时（Vercel / 自己的服务器）

4.2 托管选项#

平台	Hugo	Astro	Next.js
GitHub Pages	✅ 完美	✅ 完美	⚠️ 需要适配
Cloudflare Pages	✅ 完美	✅ 完美	⚠️ 有限支持
Netlify	✅ 完美	✅ 完美	✅ 完美
Vercel	✅ 完美	✅ 完美	✅ 原生最优
自托管 Nginx	✅ 扔文件	✅ 扔文件	⚠️ 需要 Node.js
对象存储（S3/R2）	✅ 直接上传	✅ 直接上传	❌ 不支持

Hugo 和 Astro 的纯静态输出可以部署在任何静态文件托管上——这是它们最大的运维优势。

Next.js 的部署选择受限：Vercel 是原生平台，自托管需要 Node.js 环境，Cloudflare Pages 的支持不完整。

4.3 运维复杂度#

1
运维复杂度：Next.js > Astro ≈ Hugo

Hugo 和 Astro 的运维基本上就是”上传文件”四个字。CI/CD 流程简单到极致：

1
# Hugo/Astro 的典型 CI
2
name: Deploy
3
on: [push]
4
jobs:
5
  deploy:
6
    runs-on: ubuntu-latest
7
    steps:
8
      - uses: actions/checkout@v4
9
      - run: npm install && npm run build  # Hugo 甚至不需要 npm install
10
      - run: npx pagefind --site dist      # Astro 可选
11
      - uses: cloudflare/pages-action@v1   # 部署到 Cloudflare

Next.js 的 CI/CD 相对复杂，尤其是自托管场景（需要 pm2、反向代理、环境变量管理等）。

五、实际使用体验#

5.1 Hugo —— 我在 2023 年的体验#

最早我用的就是 Hugo。它的构建速度确实让人印象深刻——上千篇文章一秒不到就构建完成。主题市场丰富，找到一个合适的主题就能很快上线。

但真正开始写内容后，痛点就来了：

想改一个细小的布局，需要学 Go Templates 的语法，文档难啃
想加一个功能（比如图片懒加载），要么找 shortcode 要么自己写
主题的”自定义”路径不直观，经常需要 override 整个模板文件
非开发者使用难度大 —— 如果只写内容不碰模板，Hugo 可以。但只要你需要定制，就要学一套和主流前端完全不同的技术栈。

5.2 Next.js —— 我在 2024 年的尝试#

作为一个前端开发者，Next.js 是我的自然选择。React 生态熟悉、组件复用方便、Vercel 部署丝滑。

但用了一段时间后也发现了问题：

我只想写个博客，但 Next.js 给我的是一整套全栈框架
App Router 的学习曲线比预期的陡 —— Server Component、RSC、'use client' 的边界需要理解
构建速度慢，100 篇文章的站点构建要 30 秒以上
部署锁定 Vercel —— 自托管太麻烦
“能力过剩” —— 博客不需要 ISR、不需要 API Routes、不需要中间件，但这些都在 bundle 里

5.3 Astro —— 最终选择#

最后选 Astro 的原因很简单：它在 Hugo 和 Next.js 之间找到了最佳平衡点。

开发体验好：写 .astro 文件就像写 HTML + JS，零学习成本
内容管理强大：Content Collections 的类型安全让我这种重视可靠性的人很安心
组件生态灵活：可以在 Astro 中用 React/Svelte/Vue 组件，不需要选边站
性能优秀：岛屿架构让页面几乎不加载 JS，速度快
部署自由：纯静态输出，扔到任何地方都能跑
集成丰富：MDX、Tailwind、Sitemap、RSS 全部官方集成，一行配置搞定

SelfStack 这个博客就是用 Astro + Svelte + Tailwind 搭建的，目前体验非常满意。

5.4 三者的典型用户画像#

1
Hugo 适合谁：
2
  ├── 非前端开发者（后端/运维/Go 开发者）
3
  ├── 大内容站点（数千篇以上）
4
  ├── 不想碰 Node.js 生态的人
5
  └── 只要博客能用就行，不想折腾
6

7
Astro 适合谁：
8
  ├── 前端开发者
9
  ├── 内容创作者 + 开发者混合身份
10
  ├── 对页面性能和 JS 体积有要求的人
11
  ├── 想要灵活性和生态（React/Vue/Svelte 混用）
12
  └── 需要 Content Collections 类型安全的人
13

14
Next.js 适合谁：
15
  ├── React 重度用户
16
  ├── 需要 API Routes / 全栈能力的站点
17
  ├── 电商/应用类网站（不只是博客）
18
  └── 准备用 Vercel 部署的人

展开收起

六、选型建议#

6.1 决策树#

1
Q: 你有多少篇文章？
2
├── < 10 篇：随便选，哪个学得快用哪个
3
├── 10 ~ 500 篇
4
│   ├── 会前端 → Astro
5
│   └── 不会前端 → Hugo
6
│   └── 必须用 React → Next.js
7
├── 500 ~ 5000 篇
8
│   ├── 性能优先 → Hugo
9
│   └── 体验优先 → Astro
10
└── > 5000 篇 → Hugo

6.2 如果你是初学者#

1
想做博客 → 会编程
2
    ├── 会前端（HTML/CSS/JS）→ Astro（最推荐）
3
    ├── 会 Go 或不想学前端 → Hugo
4
    └── 只会 React → Next.js
5
想做博客 → 不会编程
6
    ├── 完全不会写代码 → WordPress / Notion 更合适
7
    └── 愿意学一点 → Astro + 主题模板

6.3 我的个人建议#

Astro 是 2026 年搭建内容类站点（博客、文档站、公司官网）的最佳选择。它在三个方案中取得了最好的平衡：

比 Hugo 更现代、更好扩展、开发体验更好
比 Next.js 更专注、更轻量、部署更自由
两边的优点它都占了，两边的缺点它都避开了

如果你已经在用 Hugo 而且用得很顺手，没有迁移的必要。如果你已经在用 Next.js 而且需要它的全栈能力，也没必要换成 Astro。

但如果你正在选型阶段，或者对现有方案不满意——Astro 值得一试。

七、快速开始的命令对比#

Terminal window展开收起

1
# Hugo
2
hugo new site my-blog
3
cd my-blog
4
git init
5
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
6
echo "theme = 'ananke'" >> hugo.toml
7
hugo new posts/my-first-post.md
8
hugo server -D
9

10
# Astro
11
pnpm create astro@latest my-blog -- --template blog
12
cd my-blog
13
pnpm dev
14

15
# Next.js
16
npx create-next-app@latest my-blog -- --typescript --tailwind
17
cd my-blog
18
# 还需要自己配置 MDX、内容管理等...
19
npm run dev

展开收起

从零到能在浏览器看到内容，Astro 只需要两行命令。这不是偶然——Astro 从一开始就是为”内容网站”这个场景设计的。

AI 怎么改变了我记笔记的方式

Tue, 26 May 2026 00:00:00 GMT

概述#

我做了十年的知识管理。从 Evernote 到 Notion，从纸质笔记本到 Obsidian，工具换了一轮又一轮，但始终绕不开一个核心矛盾：记笔记的时间 > 用笔记的时间。

AI 的出现改变了这个等式。当大模型能理解你笔记的内容，知识管理就从”分类存储”变成了”智能调用”。

一、传统 KM 的死结#

传统知识管理的流程：

1
收集 → 整理 → 分类 → 存储 → 检索 → 使用

问题出在”整理”和”分类”——这是最耗时、最需要判断力的环节，但也是大多数人坚持不下去的环节。结果是笔记越积越多，真正用到的时候找不到。

过去几年流行的”PARA 方法”和”Zettelkasten”试图解决这个问题，但它们本质上是人的方案——靠你的判断力来决定笔记该怎么分类、怎么连接。这很累。

二、AI 如何改变知识管理#

2.1 检索：从关键词到自然语言#

过去找笔记靠文件名和标签，后来靠全文搜索。现在：

“我去年写过一个关于零信任架构的方案，里面提到了 Cloudflare Tunnel 的配置步骤，帮我找出来”

AI 理解你的意图，不需要精确的关键词。这就是语义检索带来的变化。

2.2 整理：让 AI 帮你分类#

我现在基本不做人工分类。笔记写完后，AI 自动：

提取关键概念和标签
关联已有笔记（“这篇和 XX 方案提到同一个技术点”）
建议存放位置

1
人工操作                       AI 辅助
2
──────────────────────────────────────────────
3
手动建文件夹分类                AI 自动打标签和建议分类
4
手动维护目录索引                AI 自动生成知识图谱
5
手动关联相关内容                AI 自动发现连接点
6
手动提炼摘要                    AI 自动生成摘要

2.3 创作：从碎片到文章#

这是我用得最多的场景。Obsidian 里散落着几十条相关笔记，AI 可以把它们串联成一篇结构化的文章：

指定一个主题
AI 扫描相关笔记，提取关键观点
AI 给出文章大纲
人调整方向，AI 扩写内容
人审校定稿

从碎片到成文的时间从”几天”缩短到”几小时”。

2.4 问答：对话式知识库#

传统 FAQ 是提前写好问题和答案。现在可以直接对着整个知识库提问：

“帮我看看之前 XX 学校的项目中，我们在网络安全部分是怎么设计的？有什么经验教训？”

AI 读所有相关笔记，综合回答。这在写新方案时尤其有用——不用从零思考，先看看以前是怎么做的。

三、我的 KM 系统架构#

1
┌─────────────────────────────────────────────┐
2
│                   输入层                       │
3
│   网页剪辑 · 读书笔记 · 会议记录 · 日常想法    │
4
│   微信 · 邮件 · 聊天记录 · RSS               │
5
└───────────────────┬─────────────────────────┘
6
                    ↓
7
┌─────────────────────────────────────────────┐
8
│                   存储层                       │
9
│            Obsidian（Markdown 文件）           │
10
│   按项目/领域组织，但不过度分类               │
11
└───────────────────┬─────────────────────────┘
12
                    ↓
13
┌─────────────────────────────────────────────┐
14
│                   AI 层                       │
15
│   语义检索 · 自动标签 · 关联发现 · 摘要生成   │
16
│   知识图谱 · 问答引擎 · 内容扩写             │
17
└───────────────────┬─────────────────────────┘
18
                    ↓
19
┌─────────────────────────────────────────────┐
20
│                   输出层                       │
21
│   博客文章 · 方案文档 · 汇报材料 · 知识分享   │
22
└─────────────────────────────────────────────┘

展开收起

这个架构的核心变化是：AI 层横亘在存储和输出之间，替代了人做”整理”的工作。

四、Copilot 还是 Auto-pilot#

AI 知识管理有两个方向，取决于你希望 AI 介入多少：

Copilot 模式（我当前的选择）#

AI 作为助手，你来决策：

AI 建议标签，你来确认
AI 推荐关联笔记，你来选择是否查看
AI 生成摘要，你来决定是否采用
AI 写文章初稿，你来修改定稿

适合：对自己的知识体系有控制欲、需要深度理解内容的人

Auto-pilot 模式#

AI 全自动管理知识库：

自动整理分类
自动关联连接
自动总结归档
人只在需要时提问

适合：笔记量大、时间少、以”用”为目的的人

两种模式没有优劣。我在大部分场景用 Copilot，在归档和初步整理时用 Auto-pilot。

五、工具组合#

需求	工具
笔记存储	Obsidian（Markdown + 本地优先）
AI 对话	opencode（终端 + Agentic）
语义检索	本地向量数据库（如 Chroma）
知识图谱	Obsidian Graph + AI 增强
任务管理	滴答清单（与 Obsidian 双向同步）
写作输出	opencode + proposal-writer 技能

这个组合的核心思路是：数据本地化、AI 服务化、流程自动化。笔记存在本地 Markdown，不绑定任何平台；AI 通过 API 调用，可以切换底层模型；工作流通过 opencode 串联。

六、开始的建议#

如果你想在 2026 年开始用 AI 做知识管理，不需要复杂的架构，从这四步开始：

选一个本地笔记工具（Obsidian 是最佳选择）
把所有笔记放进去（不管分类，先存再说）
接入 AI 工具（opencode 或 Obsidian Copilot 插件）
开始提问——不用整理，直接让 AI 帮你找

你会发现，之前花在”整理”上的时间，完全可以用来”思考”和”创造”。这才是知识管理的真正目的。

2026 年 AI 到底发展到哪了

Fri, 22 May 2026 00:00:00 GMT

概述#

2026 年过半，AI 不再是新闻里的概念，而是日常工作中离不开的协作者。这篇文章从模型格局、落地场景和实用建议三个角度，记录我对当前 AI 状况的观察。

一、主流模型格局#

Claude — 编程首选#

Anthropic 的 Claude 系列在 2026 年稳坐编程领域的头把交椅。长上下文（200K tokens）、深度推理能力和对代码的理解精度，让它成为开发者写代码、重构、调试的首选。配合 opencode 这类 Agentic 工具，Claude 可以自主完成从需求分析到代码实现的完整流程。

适用场景：

复杂编程任务、全栈开发
长文档分析、代码库理解
需要深度推理的技术方案设计

ChatGPT — 综合全能#

OpenAI 的 GPT-5 系列覆盖最广的场景。从日常问答、文本生成，到数据分析、DALL·E 绘图，ChatGPT 仍然是通用性最强的选择。2026 年 GPT-5 的推理速度大幅提升，价格也在持续下降。

适用场景：

日常知识问答、头脑风暴
创意写作、内容生成
多模态任务（图文理解、数据分析）
插件生态丰富的自动化工作流

DeepSeek — 性价比之王#

DeepSeek（深度求索）在 2026 年继续保持中国大模型的领先地位。V4 系列的推理能力接近 GPT-5 水平，但 API 价格低一个数量级。开源模型的生态也在快速追赶，适合预算敏感或需要本地部署的场景。

适用场景：

大规模文本处理（批量内容生成、数据标注）
私有化部署、数据安全敏感场景
成本敏感的长文本任务

其他值得关注的模型/工具#

模型/工具	定位	亮点
Gemini 3	Google 生态	与 Google Workspace 深度集成，搜索增强
Grok 4	实时信息	X 平台数据优势，实时性最强
Qwen 4	阿里系	中文理解优秀，电商/企业场景适配好
Cursor	AI IDE	将 AI 编程融入编辑器，体验最流畅
opencode	终端 AI	Agentic 模式，适合复杂工程任务和文件操作

模型选择矩阵#

1
需求                    → 推荐
2
──────────────────────────────────────────────
3
写复杂代码              → Claude + opencode
4
日常对话/写作           → ChatGPT
5
海量文本处理/自部署     → DeepSeek
6
Google 生态重度用户     → Gemini
7
追求极致编程体验        → Cursor
8
终端/工程任务           → opencode（底层可切换模型）

二、落地场景的变化#

2.1 编程：从补全到自主开发#

2024-2025 年，AI 编程还停留在”代码补全”和”简单函数生成”的阶段。到 2026 年，Agentic 模式成熟后，AI 已经可以：

理解整个项目结构，不止是当前文件
自主排查问题：读错误日志 → 定位代码 → 修复 → 验证
多文件重构：在理解全局依赖的前提下进行大规模重构
写完整测试：覆盖边界情况、Mock 外部依赖

以我自己的体验为例，用 opencode + Claude 写这个博客的某些组件，从需求描述到 PR 就绪，AI 能完成 80% 的工作，我只需要做 review 和微调。

2.2 写作：从生成到协作#

写作类 AI 在 2026 年也走出了”生成垃圾”的阶段。关键在于工作流的变化：

1
过去：prompt → 生成全文 → 修改（人改 AI 的）
2
现在：人写大纲 → AI 扩写 → 人审校 → AI 润色 → 人定稿

人机协作的比例变成了人定方向、AI 执行、人做决策。尤其是在方案编写、技术文档、会议纪要这类结构化写作中，效率提升极为明显。

2.3 知识管理：AI 成为第二大脑#

这是我最看好的方向。当 AI 能访问你的笔记、文档、任务列表时，它就不再是通用聊天机器人，而是懂你上下文的工作助手。

以我的 Obsidian + opencode 工作流为例：

AI 知道我的项目结构、客户信息、常用方案模板
写方案时自动参考历史相关内容
任务管理自然语言化：“帮我把下周的方案排个优先级”
知识检索不再是搜索关键词，而是问问题

三、关于”AI 是不是玩具”#

两年前很多人说”AI 只是个玩具”。现在回头看，说这话的人大多分为两类：

没用过最新的模型 — 还停留在 GPT-3.5 的认知水平
没有把 AI 嵌入工作流 — 偶尔用一下问个问题，觉得不够精准就放弃了

AI 真正发挥作用的前提是：

选对模型（不是越贵越好，适合场景才重要）
建立工作流（不是单次对话，而是嵌入日常流程）
持续迭代 prompt（好的对话需要调教，不是一次成型）

2026 年的 AI 不是魔法，但也不是玩具。它是个能力边界不断扩大的实习生——需要你给方向、做审核、定标准，但活干得确实快。

四、实用建议#

如果你是开发者#

把 Agentic 工具（opencode、Cursor）纳入日常工作流
学会写好的 prompt 和 system prompt
理解模型的边界——AI 擅长写代码，但不擅长理解业务

如果你是写作者/方案人#

用 AI 做扩写和润色，不要让它写初稿
建立自己的风格模板，每次对话前告诉 AI 你的风格要求
善用 humanizer-zh 这类技能去 AI 味

如果你是管理者#

关注的是工作流变革，不是单点效率
允许团队试错，建立 AI 使用的最佳实践
数据安全要优先考虑，敏感信息不要传给外部 API

五、未来半年的趋势判断#

上下文窗口继续扩大 — 很快就能把整个项目/知识库塞进一次对话
多模态更深入 — 视频理解、实时语音交互更成熟
Agent 自主性更强 — AI 可以跨多步自主决策和执行
端侧模型爆发 — 手机、PC 本地运行大模型，隐私和速度兼顾
AI 安全治理加速 — 各国法规趋于明确，企业合规需求上升

2026 年的 AI 已经不是”要不要用”的问题，而是”怎么用得好”的问题。工具摆在那里，拉开差距的是工作流和判断力。

让 AI 写代码一年了，聊聊真实感受

Mon, 18 May 2026 00:00:00 GMT

概述#

AI 编程是 2026 年落地最深、价值最明确的 AI 场景之一。但很多人的体验还停留在”生成的代码不能直接用”的阶段。问题不在 AI，在使用方法。

这篇文章分享我一年多来用 AI 编程的实践经验，覆盖日常开发的各个环节。

一、AI 编程的定位#

首先想清楚一件事：AI 不是替代你写代码，而是放大你的能力。

1
AI 擅长                     你不该让 AI 做的事
2
──────────────────────────────────────────────
3
写样板代码、CRUD             设计系统架构
4
写单元测试                   理解复杂业务规则
5
写正则、数据结构             做安全敏感的操作
6
重构/重命名/提取函数         维护依赖版本兼容性
7
查文档、写注释               写一次性密码/密钥
8
调试（读错误日志定位问题）   做代码审查的最终决策

使用 AI 的正确姿势是：你负责”做什么”和”对不对”，AI 负责”怎么写”。

二、Prompt 技巧#

2.1 给足够的上下文#

AI 没有读心术。最常犯的错误就是只丢一句”帮我写个用户管理模块”，然后怪 AI 写得不合要求。

好的 prompt 结构：

1
角色 + 任务 + 约束 + 输出格式 + 示例

示例：

你是一个资深 Python 后端开发。请为 Flask 应用实现用户注册接口。要求：

使用邮箱+密码登录，密码 bcrypt 加密

邮箱需要格式校验和唯一性检查

返回统一的 JSON 格式：{code, message, data}

用 SQLAlchemy 2.0 语法

写完后给一个完整的 curl 测试示例

2.2 分步对话，不要一次性#

复杂任务不要试图一次完成。应该像和人结对编程一样，分步沟通：

1
第 1 轮：帮我设计数据库模型
2
第 2 轮：基于这个模型，写注册 API
3
第 3 轮：现在加上邮箱验证码逻辑
4
第 4 轮：帮我写这些接口的单元测试

每一轮都在上一轮的基础上迭代，AI 的后续输出会更精准。

2.3 给 AI “自我修正”的机会#

写 prompt 时加上这句话：

在输出代码之前，先分析一下可能的问题和边界情况。

这会让 AI 先生成思考过程，再写代码，质量明显更高。

2.4 用 System Prompt 设定全局规则#

在 opencode 或 Cursor 的 system prompt 中设置全局规则：

1
- 使用 TypeScript 5.x，strict 模式
2
- React 函数组件 + Hooks，不要 class 组件
3
- 错误处理统一用 try-catch 包裹 async 函数
4
- 注释只写 Why，不写 What
5
- 单文件不超过 300 行

这样后续所有对话都会遵循这些约定，不需要每次都重复。

三、工作流设计#

3.1 我的日常开发流程#

1
需求分析
2
  │ 人写需求文档/TODO List
3
  ▼
4
方案设计
5
  │ AI 辅助出技术方案 + 人审核
6
  ▼
7
编码实现
8
  │ AI 写代码 + 人 review
9
  ▼
10
测试
11
  │ AI 写测试 + 人审查边界条件
12
  ▼
13
Code Review
14
  │ 人做最终审查 + AI 辅助检查
15
  ▼
16
部署

展开收起

每个环节的人机分工在开头的表格里。

3.2 Agentic 模式 vs Chat 模式#

1
Chat 模式（传统）                Agentic 模式（推荐）
2
──────────────────────────────────────────────
3
对话式，每次需要手动粘贴代码    自主完成多步任务
4
需要你把代码复制过去            直接读写项目文件
5
适合问问题、小段代码            适合功能开发、重构
6
工具：ChatGPT、Claude.ai        工具：opencode、Cursor

对于超过 100 行的代码任务，Agentic 模式的效率远高于 Chat 模式。opencode 可以直接操作文件系统、运行命令、读取项目上下文，完成从代码编写到测试验证的完整闭环。

3.3 测试先行#

让 AI 先写测试是一个很有效的策略：

你定义接口签名和预期行为
AI 根据描述写测试用例
你审核测试是否覆盖了关键场景
再让 AI 写实现代码
跑测试验证

这样做的好处：测试就是需求文档，AI 和人都按照同一套标准验证。

四、常见陷阱#

陷阱 1：过度信任 AI 的输出#

AI 写的代码看起来往往很合理，但可能有：

不存在的 API（幻觉）
不安全的写法（硬编码密钥、SQL 注入）
性能问题（N+1 查询、不必要的循环）

应对：每条 AI 生成的代码都要 review，像 review 新人代码一样。

陷阱 2：prompt 太模糊#

❌ “帮我改一下这个函数” ✅ “这个函数在并发场景下有问题，请用 asyncio.Lock 保护共享资源，并加上类型注解”

应对：把你对人类同事会说的话，再具体一倍。

陷阱 3：一次对话塞太多需求#

AI 的注意力有限。长对话中后面提到的需求可能被忽略。

应对：

复杂任务拆成多个子任务
重要的约束放在 prompt 末尾（AI 更容易记住最近的内容）
定期开启新对话，把关键上下文贴在开头

陷阱 4：忽略错误处理#

AI 倾向于写”快乐路径”——正常情况跑得通，异常情况直接崩。

应对：明确要求 AI 处理边界情况：

“请确保处理以下场景：传入参数为空、网络超时、数据库连接失败、并发写入冲突”

五、2026 年的最佳实践总结#

选对工具：写代码用 Claude + opencode/Cursor，不要用通用聊天工具
给够上下文：文件内容、项目结构、技术栈约束——信息越全，输出越好
分步迭代：复杂任务拆成小步骤，每一步让 AI 做完后你审核
测试先行：用测试定义需求，让 AI 按测试写实现
始终 review：AI 是协作者，不是替代者。最终责任在你
建立规则库：把常用的约束写成 system prompt，形成团队 AI 编程规范

最后一条建议：不要因为 AI 写代码快就忽略基本功。好的架构能力、领域知识、安全意识，是 AI 教不了你的——而这些恰恰是决定代码质量的关键。

MCP、API、Skill 到底啥关系

Thu, 14 May 2026 00:00:00 GMT

概述#

2025-2026 年，AI 工具生态经历了一次根本性的范式转移：AI 不再只是对话窗口里的聊天机器人，而是可以直接操作文件、调用数据库、执行命令的自主 Agent。支撑这个转变的三项关键技术——MCP、API、Skill——分别解决了不同层面的问题。

这篇文章不是零散的概念介绍，而是从历史演进的逻辑出发，讲清楚这三者各自解决什么问题、怎么用、以及它们之间的关系。

一、历史的演进：工具调用能力的三个时代#

1.1 第一代：传统 API 时代（2000s - 2023）#

API 是软件系统之间通信的标准方式。一个系统暴露 API，另一个系统通过 HTTP/PRC 调用它。这是互联网过去二十年的基础设施。

1
// 传统 REST API 调用
2
POST /api/weather/current
3
Content-Type: application/json
4
Authorization: Bearer xxx
5

6
{
7
    "city": "重庆",
8
    "units": "celsius"
9
}
10

11
// 返回
12
{
13
    "code": 200,
14
    "data": {
15
        "temperature": 28,
16
        "humidity": 75,
17
        "wind": "3级"
18
    }
19
}

展开收起

API 的特点是：接口是固定的，调用者需要知道确切的端点、参数格式、认证方式。

在 AI 出现之前，API 的调用者是人（前端开发者在浏览器中调用，后端开发者用 curl 测试，运维用脚本轮询）。API 本身没有智能，它只负责响应请求。

开发者需要阅读文档理解接口规范
参数必须精确匹配，不能有歧义
返回格式固定，需要调用方自行解析处理

这个时代的核心问题是：AI 要调用工具，需要先理解 API 文档，然后按格式组装请求。每次对接一个新工具都要写大量胶水代码。

1.2 第二代：Function Calling（2023 - 2024）#

OpenAI 在 GPT-4 时代引入了 Function Calling（函数调用），这是 AI 能调用外部工具的起点。它的核心思想是：把 API 描述告诉模型，模型自己决定什么时候调用、传什么参数。

1
{
2
    "tools": [
3
        {
4
            "type": "function",
5
            "function": {
6
                "name": "get_weather",
7
                "description": "获取指定城市的当前天气",
8
                "parameters": {
9
                    "type": "object",
10
                    "properties": {
11
                        "city": { "type": "string", "description": "城市名称" },
12
                        "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
13
                    }
14
                }
15
            }
16
        }
17
    ]
18
}

展开收起

Function Calling 的工作原理：

开发者在 API 请求中声明可用的函数（包括函数名、描述、参数 schema）
用户向 AI 提问：“重庆今天热吗？”
模型理解意图，返回一个特殊的响应：{"tool_calls": [{"name": "get_weather", "args": {"city": "重庆"}}]}
开发者拿到这个响应，在自己的代码中调用真实的 weather API
把结果返回给模型，模型生成最终回答

这比传统 API 前进了一大步：AI 可以自主决定调用哪个工具。但问题也很明显：

问题	影响
每次都要把工具描述塞进 prompt	工具多了 token 消耗巨大
没有标准化的工具发现机制	每个平台各自实现，互不兼容
工具执行由客户端完成	模型无法直接操作文件系统
没有资源模型	只能调用函数，不能”读取”或”订阅”资源

Function Calling 是一个重要的过渡方案，但它没有解决工具的标准化问题。每个 AI 平台（OpenAI、Anthropic、Google）都有自己的 function calling 格式，开发者要为每个平台写不同的适配层。

1.3 第三代：MCP 时代（2024 - 至今）#

MCP（Model Context Protocol）由 Anthropic 在 2024 年底提出，2025 年迅速成为行业标准。它解决的是 Function Calling 时代没有解决的标准化问题。

MCP 的核心思想：把工具调用从”私有协议”变成”开放标准”，就像 HTTP 把超文本传输从私有协议变成了互联网标准一样。

graph TB subgraph "Function Calling（各自为政）" A1[OpenAI 客户端] --- B1[OpenAI 工具格式] A2[Claude 客户端] --- B2[Anthropic 工具格式] A3[其他平台] --- B3[私有工具格式] end subgraph "MCP（统一标准）" C1[任何 MCP 客户端] --- D[MCP 协议] D --- E1[MCP 服务器/文件系统] D --- E2[MCP 服务器/数据库] D --- E3[MCP 服务器/GitHub] end

MCP 不是一个产品，而是一个协议。它定义了 AI 客户端（如 opencode、Claude Desktop）如何与工具服务器（如文件系统、数据库、GitHub）通信。

1.4 第四代：Skill（技能的封装）#

如果说 MCP 解决了”AI 怎么调用工具”的问题，Skill 解决的是”AI 怎么完成特定任务”的问题。

一个 Skill 是一组指令 + 工具的封装，它告诉 AI 如何完成某个领域的特定任务。比如：

“写高校信息化建设方案”这个 Skill 包含：方案模板、写作规范、相关 MCP 工具、审核标准
“代码审查”这个 Skill 包含：审查规则、安全 checklist、相关工具

Skill 在 MCP 之上再加了一层：它不只是给 AI 工具，还给了 AI 如何思考、如何决策的方法论。

二、MCP 详解#

2.1 MCP 是什么#

MCP（Model Context Protocol）是一个开放协议，定义了 AI 客户端与工具/数据源之间的通信标准。它可以理解为 “AI 应用的 USB-C 接口”——一个统一的接口让 AI 连接任何工具和数据。

1
┌─────────────────┐         MCP 协议          ┌──────────────────┐
2
│  AI 客户端       │ ◄──────────────────────► │  MCP 服务器       │
3
│  （opencode、     │                          │  （文件系统、      │
4
│   Claude Desktop、│     JSON-RPC 通信        │   数据库、GitHub、 │
5
│   VS Code 等）    │     stdin/stdout 或     │   浏览器等）       │
6
│                   │     SSE/WebSocket        │                   │
7
└─────────────────┘                           └──────────────────┘

MCP 采用了客户端-服务器架构：

MCP 客户端（通常是 AI 应用）：opencode、Claude Desktop、VS Code 扩展等
MCP 服务器（工具提供方）：暴露特定的能力，如文件读写、数据库查询、Git 操作
MCP 协议：定义两者之间的通信规范

2.2 协议传输层#

MCP 支持两种传输方式：

1
┌──────────────────────────────────────────────────┐
2
│                  传输层                           │
3
├──────────────────────────────────────────────────┤
4
│  1. stdio（标准输入/输出）                          │
5
│     MCP 服务器作为子进程启动                       │
6
│     通过 stdin/stdout 通信                        │
7
│     适合：本地工具、文件系统操作                   │
8
│                                                   │
9
│  2. SSE（Server-Sent Events）                     │
10
│     MCP 服务器作为独立 HTTP 服务运行               │
11
│     通过 HTTP 长连接通信                          │
12
│     适合：远程服务、需要共享的工具                 │
13
└──────────────────────────────────────────────────┘

stdio 传输的典型配置：

opencode.jsonc

1
{
2
    "mcp": {
3
        "filesystem": {
4
            "type": "local",
5
            "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"],
6
            "description": "安全受限的文件系统访问"
7
        }
8
    }
9
}

SSE 传输的典型配置（本地使用 npx 启动远程连接）：

1
{
2
    "mcp": {
3
        "remote-db": {
4
            "type": "local",
5
            "command": ["npx", "-y", "@mcp/server-sse-proxy", "--url", "https://mcp.example.com/sse"],
6
            "description": "远程数据库查询服务"
7
        }
8
    }
9
}

2.3 协议消息层 —— JSON-RPC#

MCP 的所有通信都基于 JSON-RPC 2.0。JSON-RPC 是一种轻量级的远程过程调用协议，和 XML-RPC 类似但使用 JSON 格式。

三种基本消息类型：

1
// 1. 请求（Request）：客户端 → 服务器
2
{
3
    "jsonrpc": "2.0",
4
    "id": 1,
5
    "method": "tools/call",
6
    "params": {
7
        "name": "read_file",
8
        "arguments": {
9
            "path": "/workspace/config.json"
10
        }
11
    }
12
}
13

14
// 2. 成功响应（Success Response）：服务器 → 客户端
15
{
16
    "jsonrpc": "2.0",
17
    "id": 1,
18
    "result": {
19
        "content": [
20
            {
21
                "type": "text",
22
                "text": "{\"server\": {\"port\": 8080}}"
23
            }
24
        ]
25
    }
26
}
27

28
// 3. 错误响应（Error Response）：服务器 → 客户端
29
{
30
    "jsonrpc": "2.0",
31
    "id": 1,
32
    "error": {
33
        "code": -32000,
34
        "message": "File not found",
35
        "data": {
36
            "path": "/workspace/config.json"
37
        }
38
    }
39
}
40

41
// 4. 通知（Notification）：无 ID，不需要响应
42
{
43
    "jsonrpc": "2.0",
44
    "method": "notifications/initialized"
45
}

展开收起

为什么用 JSON-RPC 而不是 REST？ JSON-RPC 更适合 MCP 的场景：

特性	REST	JSON-RPC
接口定义	URL + Method 组合	一个端点，method 字段区分
批量操作	不支持（需要多个请求）	支持一次发送多个请求
双向通信	请求-响应模式	支持服务器主动推送通知
连接数	一个连接处理一个请求	一个连接处理多个请求（复用）
适用场景	资源型 CRUD	动作型/过程型调用

MCP 的核心是”调用工具”和”获取资源”，这是动作型的，天然适合 JSON-RPC。

2.4 MCP 的原语#

MCP 定义了三种核心原语，对应 AI 与工具交互的三种基本模式：

原语一：Tools（工具）#

Tools 是 AI 可以调用的函数。每个 tool 有名称、描述和输入参数定义。这是 MCP 最常用的原语，对应 Function Calling 的”函数调用”。

1
// MCP 服务器的工具声明
2
{
3
    "tools": [
4
        {
5
            "name": "read_file",
6
            "description": "读取指定路径的文件内容",
7
            "inputSchema": {
8
                "type": "object",
9
                "properties": {
10
                    "path": {
11
                        "type": "string",
12
                        "description": "文件路径"
13
                    }
14
                },
15
                "required": ["path"]
16
            }
17
        },
18
        {
19
            "name": "write_file",
20
            "description": "写入内容到指定文件",
21
            "inputSchema": {
22
                "type": "object",
23
                "properties": {
24
                    "path": { "type": "string" },
25
                    "content": { "type": "string" },
26
                    "append": { "type": "boolean", "description": "是否追加模式" }
27
                },
28
                "required": ["path", "content"]
29
            }
30
        }
31
    ]
32
}

展开收起

关键特性：

AI 客户端通过 tools/list 获取可用工具列表
AI 通过 tools/call 调用具体工具
工具执行结果以结构化内容返回（text、image、resource 等类型）
工具是”有副作用的”——调用工具可能会修改系统状态

MCP 服务器中注册工具的实际代码（以 TypeScript 为例，用官方 SDK）：

1
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
2
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
import {
4
    CallToolRequestSchema,
5
    ListToolsRequestSchema,
6
} from "@modelcontextprotocol/sdk/types.js";
7

8
const server = new Server(
9
    { name: "example-fs-server", version: "1.0.0" },
10
    { capabilities: { tools: {} } }
11
);
12

13
// 处理 tools/list 请求
14
server.setRequestHandler(ListToolsRequestSchema, async () => ({
15
    tools: [
16
        {
17
            name: "read_file",
18
            description: "读取文件内容",
19
            inputSchema: {
20
                type: "object",
21
                properties: {
22
                    path: { type: "string" }
23
                },
24
                required: ["path"]
25
            }
26
        }
27
    ]
28
}));
29

30
// 处理 tools/call 请求
31
server.setRequestHandler(CallToolRequestSchema, async (request) => {
32
    const { name, arguments: args } = request.params;
33

34
    if (name === "read_file") {
35
        const content = await fs.readFile(args.path, "utf-8");
36
        return {
37
            content: [{ type: "text", text: content }]
38
        };
39
    }
40

41
    throw new Error(`Unknown tool: ${name}`);
42
});
43

44
// 启动服务器（stdio 传输）
45
const transport = new StdioServerTransport();
46
await server.connect(transport);

展开收起

原语二：Resources（资源）#

Resources 是 AI 可以读取的”数据源”。和 Tools 不同，Resources 是无副作用的——读取资源不会改变系统状态。

1
{
2
    "resources": [
3
        {
4
            "uri": "file:///workspace/config.json",
5
            "name": "Project Configuration",
6
            "description": "项目配置文件",
7
            "mimeType": "application/json"
8
        },
9
        {
10
            "uri": "file:///workspace/README.md",
11
            "name": "Project README",
12
            "description": "项目说明文档",
13
            "mimeType": "text/markdown"
14
        }
15
    ]
16
}

展开收起

Resources 的用途：AI 客户端可以通过 resources/list 获取资源列表，通过 resources/read 读取资源内容。这比 Tools 更轻量——AI 不需要”调用”，只需要”读取”。

实际场景：AI 在开始编码之前，通过 Resources 读取项目的 package.json、README、配置文件，了解项目上下文。

原语三：Prompts（提示模板）#

Prompts 是预定义的提示词模板，封装了特定场景的最佳实践。

1
{
2
    "prompts": [
3
        {
4
            "name": "code_review",
5
            "description": "执行代码审查",
6
            "arguments": [
7
                {
8
                    "name": "language",
9
                    "description": "编程语言",
10
                    "required": true
11
                }
12
            ]
13
        }
14
    ]
15
}

展开收起

Prompts 的用途：客户端可以获取这些模板并呈现给用户。用户选择后填充参数，模板展开成完整的 prompt。这本质上是”可复用的 AI 指令”。

2.5 会话生命周期#

一个完整的 MCP 会话流程：

1
客户端                              MCP 服务器
2
  │                                      │
3
  │  ── 1. 建立连接（stdio/SSE）─────► │
4
  │                                     │
5
  │  ◄── 2. server.info ─────────────── │
6
  │       (名称、版本、能力声明)          │
7
  │                                     │
8
  │  ── 3. initialize ────────────────► │
9
  │       (客户端信息、协议版本)          │
10
  │                                     │
11
  │  ◄── 4. initialized ──────────────  │
12
  │       (确认初始化完成)               │
13
  │                                     │
14
  │  ── 5. tools/list ────────────────► │
15
  │  ◄── [tool1, tool2, ...] ─────────  │
16
  │                                     │
17
  │  ── 6. tools/call(name="read")───►  │
18
  │  ◄── {content: "..."} ────────────  │
19
  │                                     │
20
  │  ── 7. tools/call(name="write")──►  │
21
  │  ◄── {content: "ok"} ─────────────  │
22
  │                                     │
23
  │  ── 8. 关闭连接 ──────────────────► │

展开收起

2.6 MCP 的完整流程：以 opencode 为例#

以 opencode 中通过 MCP 操作文件为例，展示完整的端到端流程：

步骤 1：配置 MCP 服务器

在 opencode.jsonc 中声明：

1
{
2
    "mcp": {
3
        "filesystem": {
4
            "type": "local",
5
            "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/tanzicai/CX"],
6
            "description": "文件系统操作"
7
        }
8
    }
9
}

步骤 2：opencode 启动时加载 MCP

opencode 启动时，检测到配置中的 MCP 服务器配置，为每个服务器启动一个子进程：

1
opencode 进程
2
    │
3
    ├── 主进程（处理对话）
4
    │
5
    └── 子进程：@modelcontextprotocol/server-filesystem
6
         │ 通过 stdin/stdout 与主进程通信
7
         │ 能力：在 /Users/tanzicai/CX 范围内读写文件

步骤 3：用户提问

用户输入：“帮我把这个目录下的所有 .md 文件列出来”

步骤 4：AI 决定调用工具

大模型（Claude/GPT）收到用户的自然语言请求，结合可用的工具列表，决定调用 read_file 和 read_directory 等工具。

步骤 5：opencode 通过 MCP 执行

1
// opencode → MCP 服务器
2
{
3
    "jsonrpc": "2.0",
4
    "id": 1,
5
    "method": "tools/call",
6
    "params": {
7
        "name": "read_directory",
8
        "arguments": { "path": "/Users/tanzicai/CX" }
9
    }
10
}
11

12
// MCP 服务器 → opencode
13
{
14
    "jsonrpc": "2.0",
15
    "id": 1,
16
    "result": {
17
        "content": [
18
            {
19
                "type": "text",
20
                "text": "[\"README.md\", \"package.json\", \"src/\", ...]"
21
            }
22
        ]
23
    }
24
}

展开收起

步骤 6：AI 组织回答

模型拿到结果后，再结合对话上下文，用自然语言回复用户。

这个过程中，用户完全不需要知道底层的 MCP 通信细节。MCP 对用户是完全透明的——用户看到的是”AI 帮我操作了文件”，看不到的是背后的一系列 JSON-RPC 调用。

2.7 MCP 的核心价值#

MCP 相比前代技术的核心进步：

特性	传统 API	Function Calling	MCP
标准化	每个 API 各自定义	每个平台各自定义	统一协议
工具发现	读文档	API 定义中声明	tools/list
资源模型	无	无	Resources 原语
订阅机制	无	无	支持服务器推送
传输协议	HTTP	HTTP	stdio / SSE
互操作性	低	低	高
安全性	各自实现	各自实现	统一能力边界

三、API 详解#

3.1 API 的本质#

API（Application Programming Interface）是软件系统之间预定好的通信契约。它定义了：

我能做什么（端点/方法）
你需要给我什么（请求参数）
我会返回什么（响应格式）

API 的核心设计原则是约定大于配置——一旦约定确定，调用方和提供方可以独立开发和演进。

3.2 API 的类型#

graph TB API[API 类型] --> REST[RESTful API] API --> GraphQL[GraphQL] API --> gRPC[gRPC] API --> WebSocket[WebSocket API] API --> RPC[JSON-RPC / XML-RPC] REST --> H1[基于 HTTP 方法] REST --> H2[资源导向 URL] REST --> H3[无状态] GraphQL --> G1[单一端点] GraphQL --> G2[客户端定义查询] GraphQL --> G3[避免过度获取] gRPC --> R1[基于 Protocol Buffers] gRPC --> R2[双向流式通信] gRPC --> R3[强类型]

类型	数据格式	适用场景	优点	缺点
REST	JSON/XML	通用的 CRUD 操作	简单、缓存友好	过度获取/不足获取
GraphQL	GraphQL DSL	复杂数据查询	精确获取、强类型	缓存复杂、查询性能难预测
gRPC	Protobuf	微服务间通信	高性能、强类型、流式	浏览器支持有限
WebSocket	任意	实时通信	双向、低延迟	无标准消息格式
JSON-RPC	JSON	动作调用、工具调用	简单直接	发现机制有限

3.3 REST API 标准#

REST 是目前最常见的 API 风格，对理解 MCP 也有帮助（MCP 和 REST 的设计哲学有相似之处）：

1
# 资源导向的 URL 设计
2
GET    /api/users           # 列出用户
3
POST   /api/users           # 创建用户
4
GET    /api/users/{id}      # 获取单个用户
5
PUT    /api/users/{id}      # 全量更新用户
6
PATCH  /api/users/{id}      # 部分更新用户
7
DELETE /api/users/{id}      # 删除用户
8

9
# 状态码规范
10
200 OK                      # GET/PUT/PATCH 成功
11
201 Created                 # POST 成功创建
12
204 No Content              # DELETE 成功
13
400 Bad Request             # 参数错误
14
401 Unauthorized            # 未认证
15
403 Forbidden               # 无权限
16
404 Not Found               # 资源不存在
17
500 Internal Server Error   # 服务器内部错误

展开收起

3.4 AI 时代 API 的新角色#

在 AI 时代，API 的角色发生了微妙但重要的变化：

变化一：AI 是新的 API 消费者

过去 API 的消费者是人（前端开发者调用后端 API）。现在 API 的消费者是 AI。这意味着 API 的设计需要考虑：

更自然的错误信息（AI 需要理解错误原因，而不是只看 status code）
更丰富的描述信息（AI 需要知道 API 是做什么的，而不是只看 endpoint）
更一致的返回格式（AI 不像人一样能灵活适应不同的返回结构）

变化二：API 文档从给人看变成给 AI 看

1
## API 文档的传统写法（给人看）
2

3
### 获取天气
4
接口地址：GET /api/weather
5
参数：
6
  - city：城市名称
7
  - units：单位（celsius/fahrenheit）
8
返回示例：
9
  { "temperature": 28, "humidity": 75 }
10

11
## API 文档的 AI 友好写法
12

13
### get_weather
14
用途：获取指定城市的天气预报数据
15
适用场景：用户在询问天气、需要决定出行安排时调用
16
参数：
17
  - city：必填，城市中文名称如"重庆"、"北京"
18
  - units：可选，默认 celsius
19
行为约束：不要同时查询多个城市，一次只查一个
20
返回字段说明：
21
  - temperature：当前温度，整数
22
  - humidity：湿度百分比
23
  - wind：风力等级描述
24
错误处理：如果城市不存在，返回 404，此时应告知用户城市名可能错误

展开收起

变化三：从 API 到 MCP 的演进

API 是”人 → 机器”的接口，MCP 是”AI → 工具”的接口。MCP 并没有取代 API——相反，MCP 服务器内部通常会调用底层 API。

1
AI 客户端
2
    │
3
    │  MCP 协议
4
    ▼
5
MCP 服务器
6
    │
7
    │  传统 API（HTTP/REST/gRPC）
8
    ▼
9
后端服务（数据库、文件系统、GitHub）

MCP 是 API 的上层抽象——它为 AI 消费 API 提供了标准化的接口，屏蔽了底层 API 的差异性。

四、Skill 详解#

4.1 Skill 是什么#

Skill 是面向 AI 的任务能力封装。它是一组指令、规则、工具引用和工作流程的集合，让 AI 能够完成特定领域的复杂任务。

如果说 API 和 MCP 是”给了 AI 可以用的工具”，那么 Skill 是”教 AI 怎么用这些工具完成一项工作”。

1
# Skill 的结构化描述
2
name: proposal-writer              # 技能名称
3
description: 编写高校信息化建设方案   # 技能描述
4
version: 1.0.0
5

6
# 核心指令（告诉 AI 如何思考）
7
instructions:
8
  - 你是一个拥有10年经验的高校信息化顾问
9
  - 写方案前先理解客户需求，列出大纲
10
  - 每个方案必须包含：项目背景、建设目标、技术架构、实施计划、预算
11
  - 用正式书面语，专业术语需加括号备注英文
12
  - 避免过度技术化，突出业务价值
13

14
# 引用的 MCP 工具
15
mcp_tools:
16
  - filesystem:    # 读取方案模板和参考资料
17
  - web:           # 搜索相关政策和标准
18

19
# 参考文件
20
references:
21
  - path: /templates/proposal-template.docx
22
  - path: /guidelines/writing-style.md

展开收起

4.2 Skill 的来源#

Skill 的概念源于几个方向的交汇：

1. Prompt Engineering 的演化

最早人们用简单的 prompt 让 AI 做事。随着任务变复杂，prompt 越来越长，越来越结构化。最终人们发现：prompt 本身可以成为一种可共享、可复用的资产。这就是 Skill 的雏形。

1
单轮 prompt              多轮 prompt              System Prompt           Skill
2
   │                        │                        │                    │
3
   ▼                        ▼                        ▼                    ▼
4
"帮我写个方案"    →  第一轮列大纲              你是一个顾问            结构化指令
5
                    第二轮写正文              请遵循以下规则          + 工具引用
6
                    第三轮润色                ...                    + 参考文件
7
                                                                     + 工作流程

2. MCP 的补充

MCP 解决了”AI 能调用什么工具”，但没有解决”AI 应该怎么调用这些工具来完成任务”。Skill 在 MCP 之上补充了这个缺失的环节。

1
MCP 层面：AI 有文件系统工具、有数据库工具、有网络搜索工具
2
Skill 层面：AI 知道写方案时需要先读模板、再查政策、再写正文、最后审核

3. 人机协作工作流的固化

很多 AI 使用场景已经形成了固定的工作流。Skill 把这些工作流固化下来，变成可复用的模式。

所有 Skill 本质上都是对”人类最佳实践”的封装。

4.3 Skill 的实现机制#

以 opencode 的 Skill 为例，深入理解 Skill 的工作方式：

Skill 的物理存储：Skill 是一个目录，包含：

1
~/.config/opencode/skills/proposal-writer/
2
├── SKILL.md          # 核心指令文件
3
├── references/       # 参考文件
4
│   ├── template.docx
5
│   └── style-guide.md
6
└── scripts/         # 辅助脚本（可选）
7
    └── generate-docx.py

SKILL.md 的核心内容：

1
# proposal-writer
2

3
你是一个资深的高校信息化建设顾问。
4
你的任务是帮助用户编写高质量的建设方案、可行性报告和投标文件。
5

6
## 工作流程
7

8
1. 需求分析
9
   - 先理解用户的学校类型、预算规模、核心需求
10
   - 列出方案大纲，请用户确认
11

12
2. 方案编写
13
   - 参考 /references/ 中的模板格式
14
   - 每个章节包含：核心观点 → 详细展开 → 案例支撑
15
   - 使用 MCP 文件系统工具读取已有的方案作为参考
16

17
3. 审核
18
   - 自检清单：
19
     [ ] 是否有明确的建设目标
20
     [ ] 技术架构是否合理
21
     [ ] 预算是否具体
22
     [ ] 实施计划是否可行
23

24
4. 输出
25
   - 生成 Markdown 版本供用户在 Obsidian 中编辑
26
   - 如有需要，使用 generate-docx.py 生成 Word 版本
27

28
## 写作规范
29

30
- 使用正式书面语，不使用口语化表达
31
- 英文专业术语保留并加括号备注中文
32
- 每个段落不超过 5 句话
33
- 不使用"首先其次最后"等模板化过渡词

展开收起

Skill 的加载过程：

1
用户输入："帮我写一份智慧课堂的建设方案"
2
    │
3
    ▼
4
opencode 检测到任务类型
5
    │
6
    ▼
7
加载对应的 Skill（proposal-writer 技能）
8
    │
9
    ├── 读取 SKILL.md → 注入系统 prompt
10
    ├── 加载 MCP 工具引用
11
    └── 提供参考文件路径
12
    │
13
    ▼
14
AI 开始按照 Skill 定义的工作流执行任务

加载 Skill 后，系统 prompt 相当于变成了：

1
[系统指令]
2
你是一个资深的高校信息化建设顾问...
3
你的工作流程是：
4
1. 需求分析...
5
2. 方案编写...
6
3. 审核...
7
4. 输出...
8

9
[可用工具]
10
- filesystem MCP（读写文件）
11
- web MCP（搜索信息）
12

13
[用户问题]
14
帮我写一份智慧课堂的建设方案

4.4 Skill 的分类#

类型	示例	核心内容
写作类	proposal-writer、doc-generator	写作规范、模板、审核清单
分析类	tech-review、code-reviewer	分析框架、检查项、评分标准
设计类	solution-architect、project-plan	设计原则、方法论、模板
优化类	humanizer-zh	去 AI 味规则、替换词表
配置类	customize-opencode	配置项说明、最佳实践

4.5 Skill 与 MCP 的关系#

Skill 和 MCP 不是竞争关系，而是互补的层级关系：

1
                    ┌──────────────────────┐
2
                    │       Skill          │
3
                    │  （任务能力封装）      │
4
                    │  如何完成特定工作     │
5
                    └──────────┬───────────┘
6
                               │ 使用
7
                    ┌──────────▼───────────┐
8
                    │       MCP            │
9
                    │  （工具访问协议）      │
10
                    │  如何调用外部工具     │
11
                    └──────────┬───────────┘
12
                               │ 调用
13
                    ┌──────────▼───────────┐
14
                    │       API            │
15
                    │  （系统通信接口）      │
16
                    │  系统间如何通信       │
17
                    └──────────────────────┘

展开收起

Skill 使用 MCP 工具：一个 Skill 可以声明它需要哪些 MCP 工具。当 Skill 被加载时，对应的 MCP 服务器也被激活。

MCP 调用底层 API：MCP 服务器的实现内部往往会调用传统 API。比如一个 GitHub MCP 服务器内部调用 GitHub REST API。

API 提供基础能力：API 是软件通信的基础设施，MCP 和 Skill 都建立在 API 之上。

这种层级关系类似于前端开发的”组件 → 框架 → 浏览器 API”：

1
Skill（组件：封装了 UI 和行为）
2
    │
3
MCP（框架：提供了标准化的接口）
4
    │
5
API（浏览器 API：操作系统能力）

五、三者的协作实战#

5.1 完整场景：用 opencode 写一篇博客#

以我写博客为例，展示三个层级的协作：

1
用户："帮我写一篇关于 MCP 的技术博客"
2

3
1. Skill 层加载
4
   └── opencode 加载 doc-generator 技能
5
       ├── 写作规范：技术文章结构
6
       ├── 风格指南：清晰、有代码示例
7
       └── 工作流：大纲 → 初稿 → 审校
8

9
2. MCP 层调用
10
   ├── filesystem：读取已有的博客文章作为参考
11
   ├── git：创建新分支、提交文件
12
   └── web：搜索相关资料
13

14
3. API 层通信
15
   ├── Anthropic API：调用 Claude 模型
16
   ├── GitHub API：通过 MCP 的 git 工具调用
17
   └── 文件系统 API：通过 MCP 的 filesystem 调用

展开收起

用户看到的只有一句话的输入，背后是三层协议的协同工作。

5.2 从零开始配置的完整流程#

如果你是一个开发者想搭建自己的 AI 工作环境，三个层级的配置示例：

第一步：获取 API Key（API 层）

Terminal window

1
# 注册并获取 AI 模型的 API Key
2
export ANTHROPIC_API_KEY=sk-ant-xxx
3
export OPENAI_API_KEY=sk-xxx
4

5
# 其他可能需要 API 的服务
6
export GITHUB_TOKEN=ghp_xxx
7
export NOTION_API_KEY=ntn_xxx

第二步：配置 MCP 服务器（MCP 层）

opencode.jsonc展开收起

1
{
2
    "mcp": {
3
        "filesystem": {
4
            "type": "local",
5
            "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/workspace"],
6
            "description": "在 workspace 范围内读写文件"
7
        },
8
        "github": {
9
            "type": "local",
10
            "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
11
            "environment": {
12
                "GITHUB_TOKEN": "${GITHUB_TOKEN}"
13
            },
14
            "description": "GitHub 仓库操作"
15
        },
16
        "ticktick": {
17
            "type": "local",
18
            "command": ["npx", "-y", "@ticktick/mcp-server"],
19
            "environment": {
20
                "API_TOKEN": "${TICKTICK_TOKEN}"
21
            },
22
            "description": "滴答清单任务管理"
23
        }
24
    }
25
}

展开收起

第三步：安装 Skill（Skill 层）

Terminal window

1
# 从官方仓库安装 Skill
2
opencode skill install proposal-writer
3
opencode skill install doc-generator
4
opencode skill install tech-review
5

6
# 加载 Skill
7
opencode skill load proposal-writer
8

9
# 现在你可以说：
10
# "帮我把这个需求写成建设方案"
11
# AI 就会按照 Skill 定义的工作流执行

5.3 协议对比一览#

维度	API	MCP	Skill
诞生时间	2000s	2024	2025
核心问题	系统间如何通信	AI 如何调用工具	AI 如何完成任务
接口形式	HTTP 端点	JSON-RPC 方法	Markdown 指令
数据格式	JSON/XML/Protobuf	JSON-RPC	Markdown/YAML
传输方式	HTTP/HTTPS	stdio/SSE	文件加载
发现机制	文档/OpenAPI	tools/list	skill list
消费者	开发者	AI 模型	AI Agent
标准化组织	IETF/W3C	Anthropic 主导	各平台自定义
生态规模	千万级	千级（快速增长）	百级（早期）
相互依赖	基础层	依赖 API	依赖 MCP + API

六、趋势与展望#

6.1 MCP 的下一步#

MCP over HTTP：目前 stdio 传输占主导，未来 SSE/WebSocket 会普及，远程 MCP 服务器会成为主流
MCP Registry：类似 npm 或 Docker Hub 的 MCP 服务器注册中心，方便发现和安装工具
权限模型：更细粒度的权限控制，让用户可以精确控制 AI 能做什么
流式结果：工具返回大文件时支持流式传输

6.2 API 的演变方向#

AI-native API：新 API 在设计时就考虑 AI 消费场景，提供语义描述和意图理解支持
API 即 MCP：越来越多的服务直接提供 MCP 接口，而不仅仅是 REST API
智能 API 网关：网关层自动将传统 API 包装成 MCP 兼容接口

6.3 Skill 的生态化#

Skill Store：类似 App Store 的技能市场，用户可以安装分享的技能
Skill 组合：多个 Skill 串联成复杂工作流（proposal-writer + humanizer-zh 自动衔接）
社区标准化：Skill 格式可能走向标准化，跨平台兼容

七、写在最后#

API、MCP、Skill 代表了技术抽象的三个层级：

API 定义了能力：系统之间能做什么
MCP 标准化了接入：AI 怎么发现和使用这些能力
Skill 封装了知识：怎么用这些能力完成有价值的工作

这三者的关系不是替代，而是递进。Skill 依赖于 MCP，MCP 依赖于 API。每一层都在前一层的肩膀上解决新问题。

如果你是一个开发者，我的建议是：

API 是基本功：理解 REST 设计原则、JSON-RPC 协议、认证机制，这些是底层通用知识
MCP 是现在：2026 年 MCP 已经是最重要的 AI 工具协议，学会写 MCP 服务器是一项高价值技能
Skill 是未来：当工具的接入问题被 MCP 解决后，真正的价值在于”怎么让 AI 更好地完成特定任务”

十年后回头看，API 会成为基础设施（就像今天的 TCP/IP），MCP 会成为标准协议（就像今天的 HTTP），而 Skill 会成为 AI 时代的”编程语言”——定义一个 Skill 就像今天写一个函数，定义输入输出和工作逻辑。

这个变化才刚刚开始。

博达网站群改来改去那些事：模板、栏目、发布的完整流程

Sun, 10 May 2026 00:00:00 GMT

概述#

博达网站群管理平台（以下简称博达）是国内高校和政府机构中占有率最高的网站群 CMS 之一。它的核心设计理念是”网站群”——一套后台管理多个站点，模板驱动内容呈现，实现统一运维、分级管理。

对技术人员来说，理解博达的内部机制不只是为了运维，更是为了做二次开发和深度定制。这篇文章从源码实现层面解析博达的工作流程：模板怎么做、栏目怎么建、资料怎么管、页面怎么发。

一、整体架构#

1.1 分层设计#

博达采用经典的四层架构：

1
┌──────────────────────────────────────────────────┐
2
│                    展示层                          │
3
│     FreeMarker 模板 (.ftl)  +  JSP 视图           │
4
│     HTML/CSS/JS  ·  前台页面渲染                  │
5
├──────────────────────────────────────────────────┤
6
│                    控制层                          │
7
│     Servlet / Spring MVC Controller               │
8
│     请求分发 · 参数解析 · 权限校验                │
9
├──────────────────────────────────────────────────┤
10
│                    业务层                          │
11
│     Service · Manager · 发布引擎                  │
12
│     栏目管理 · 资料管理 · 模板管理 · 发布调度     │
13
├──────────────────────────────────────────────────┤
14
│                    数据层                          │
15
│     DAO / MyBatis / JDBC                          │
16
│     栏目表 · 资料表 · 模板表 · 站点表 · 日志表   │
17
└──────────────────────────────────────────────────┘

展开收起

1.2 核心模块#

模块	功能	技术实现
站点管理	多站点创建、域名绑定、站点级配置	站点表驱动，每个站点独立目录
栏目管理	树形栏目结构、层级控制、访问权限	递归树结构，parentId 关联
模板管理	FreeMarker 模板上传、编辑、预览	模板存储在文件系统或 DB
资料管理	文档、图片、附件的内容库	资料表 + 文件系统双存储
发布引擎	静态页面生成、增量/全量发布	FreeMarker + 文件 IO
用户权限	角色管理、站点级/栏目级权限	RBAC 模型
系统配置	全局参数、站点参数、字典管理	properties + 配置表

1.3 请求处理流程#

1
浏览器请求
2
    ↓
3
Nginx/Apache（反向代理）
4
    ↓
5
Tomcat（Servlet 容器）
6
    ↓
7
web.xml 中的 Servlet 过滤器链
8
    ↓  SiteFilter: 解析站点域名
9
    ↓  AuthFilter: 校验登录状态
10
    ↓
11
核心分发 Servlet（处理动态请求）
12
    ├─ /admin/* → 后台管理模块
13
    ├─ /api/*   → RESTful API
14
    └─ /*       → 前台页面访问
15
         ↓
16
    判断是否静态页面
17
    ├─ 是 → 直接返回已生成的 HTML
18
    └─ 否 → 调用发布引擎动态渲染
19
         ↓
20
    FreeMarker 解析模板 → 输出 HTML

展开收起

二、FreeMarker 模板系统#

FreeMarker 是博达的核心渲染引擎。理解 FreeMarker 的工作原理，就理解了博达的一半。

2.1 FreeMarker 是什么#

FreeMarker 是一个基于 Java 的模板引擎，它将模板文件（.ftl）和数据模型（Java 对象）合并，输出文本（通常是 HTML）。它的核心是 Template + Data Model = Output。

1
模板（.ftl）:    <h1>${title}</h1>
2
数据模型:       {"title": "欢迎访问"}
3
输出:           <h1>欢迎访问</h1>

FreeMarker 不是 Servlet，不是 JSP，它只是一个引擎——模板本身不处理业务逻辑，只负责渲染。

2.2 博达中的 FreeMarker 实现#

博达在 FreeMarker 基础上封装了自己的标签库和指令集。这里的关键在于两个层面：

一是博达自定义的 FreeMarker 指令，比如获取栏目列表、获取资料列表等功能的标签。这些指令实际上对应了后端 Java 类的执行逻辑。

二是模板中的变量来源，模板中的 ${xxx} 变量由后端 Java 代码在渲染时注入，这些变量可能来自数据库查询、请求参数、或系统配置。

核心标签库示例#

1
<#-- 获取栏目列表 -->
2
<@cms.channelList siteId="1" parentId="0">
3
  <#list channels as channel>
4
    <li>
5
      <a href="${channel.url}">${channel.name}</a>
6
      <#if channel.hasChildren>
7
        <@cms.channelList siteId="1" parentId="${channel.id}">
8
          <ul>
9
            <#list channels as subChannel>
10
              <li><a href="${subChannel.url}">${subChannel.name}</a></li>
11
            </#list>
12
          </ul>
13
        </@cms.channelList>
14
      </#if>
15
    </li>
16
  </#list>
17
</@cms.channelList>
18

19
<#-- 获取资料列表 -->
20
<@cms.contentList siteId="1" channelId="2" pageNo="1" pageSize="20">
21
  <#list contents as content>
22
    <article>
23
      <h2><a href="${content.url}">${content.title}</a></h2>
24
      <p>${content.publishDate?string("yyyy-MM-dd")}</p>
25
      <div>${content.summary}</div>
26
    </article>
27
  </#list>
28
</@cms.contentList>
29

30
<#-- 获取单条资料详情 -->
31
<@cms.contentDetail contentId="${id}">
32
  <h1>${content.title}</h1>
33
  <div>${content.author} | ${content.publishDate?string("yyyy-MM-dd")}</div>
34
  <div>${content.content}</div>
35
</@cms.contentDetail>
36

37
<#-- 获取站点配置 -->
38
${site.name}
39
${site.domain}
40
${site.icp}
41

42
<#-- 获取系统参数 -->
43
${config("siteTitle")}
44
${config("statCode")}

展开收起

2.3 自定义标签的 Java 实现#

以上这些自定义标签，在博达的后端源码中对应的是 Java 类。每个自定义标签都实现了 FreeMarker 的 TemplateDirectiveModel 接口。

加载博达标签就是在 FreeMarker 配置中注册这些自定义指令。博达的初始化代码通常会这样做：

1
// 注册自定义标签的核心逻辑
2
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
3
cfg.setServletContextForTemplateLoading(servletContext, "/WEB-INF/templates");
4
cfg.setDefaultEncoding("UTF-8");
5
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
6

7
// 注册博达自定义指令
8
cfg.setSharedVariable("cms", new CmsDirectiveGroup());
9
// 其中 CmsDirectiveGroup 内部包含：
10
// - channelList → ChannelListDirective
11
// - contentList → ContentListDirective
12
// - contentDetail → ContentDetailDirective
13
// - siteInfo → SiteInfoDirective

ChannelListDirective 实现示例#

1
public class ChannelListDirective implements TemplateDirectiveModel {
2

3
    private ChannelService channelService; // 注入栏目服务
4

5
    @Override
6
    public void execute(Environment env, Map params, TemplateModel[] loopVars,
7
                        TemplateDirectiveBody body) throws TemplateException, IOException {
8
        // 1. 解析参数
9
        String siteId = getRequiredParam(params, "siteId");
10
        String parentId = getParam(params, "parentId", "0");
11
        Integer depth = getIntParam(params, "depth", null);
12

13
        // 2. 调用业务层获取数据
14
        List<Channel> channels = channelService.getChannelList(siteId, parentId, depth);
15

16
        // 3. 将数据注入模板上下文
17
        DefaultObjectWrapperBuilder builder = new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_32);
18
        env.setVariable("channels", builder.build().wrap(channels));
19

20
        // 4. 渲染模板体
21
        if (body != null) {
22
            body.render(env.getOut());
23
        }
24
    }
25
}

展开收起

当模板解析到 <@cms.channelList> 时，FreeMarker 就会调用 ChannelListDirective.execute()，查询数据库，将结果注入模板变量 channels，然后渲染标签体中的内容。

2.4 模板中的常用 FreeMarker 语法#

变量插值#

1
${variable}              <#-- 简单变量 -->
2
${variable!}             <#-- 变量不存在时输出空字符串 -->
3
${variable!"默认值"}      <#-- 变量不存在时输出默认值 -->
4
${variable?if_exists}    <#-- 旧版写法，等价于 ! -->
5
${(object.property)!}    <#-- 对象属性，且防止 NullPointer -->

条件判断#

1
<#if condition>
2
  ...
3
<#elseif condition2>
4
  ...
5
<#else>
6
  ...
7
</#if>
8

9
<#-- 判断列表是否为空 -->
10
<#if list?? && list?size gt 0>
11
  ...
12
</#if>
13

14
<#-- 三元表达式 -->
15
${condition?string("yes", "no")}

展开收起

循环#

1
<#list list as item>
2
  ${item?index}  <#-- 索引，从 0 开始 -->
3
  ${item?counter} <#-- 计数，从 1 开始 -->
4
  ${item.name}
5
  <#if item?is_last?string("last", "")></#if>
6
<#else>
7
  列表为空
8
</#list>
9

10
<#-- 取前 N 个 -->
11
<#list list[0..4] as item>
12
  ...
13
</#list>

内建函数#

1
${str?length}                  <#-- 字符串长度 -->
2
${str?substring(0, 10)}        <#-- 截取 -->
3
${str?trim}                    <#-- 去空格 -->
4
${str?html}                    <#-- HTML 转义 -->
5
${str?cap_first}               <#-- 首字母大写 -->
6
${date?string("yyyy-MM-dd")}   <#-- 日期格式化 -->
7
${number?string("0.00")}       <#-- 数字格式化 -->
8
${htmlContent?no_esc}          <#-- 不转义输出 HTML（危险！） -->

include 与 import#

1
<#-- 包含公共文件 -->
2
<#include "/common/header.ftl">
3
<#include "/common/footer.ftl">
4

5
<#-- 导入宏库 -->
6
<#import "/common/macros.ftl" as mac>
7
<@mac.pagination pageNo=1 totalPages=10/>

2.5 模板文件的管理#

博达的模板文件通常存放在以下位置：

1
WEB-INF/templates/
2
├── _common/                  # 公共模板
3
│   ├── header.ftl            # 页头
4
│   ├── footer.ftl            # 页脚
5
│   ├── head.ftl              # <head> 部分
6
│   ├── nav.ftl               # 导航栏
7
│   ├── sidebar.ftl           # 侧边栏
8
│   └── macros.ftl            # 宏定义
9
├── index/                    # 首页模板
10
│   ├── index.ftl             # 首页
11
│   └── index_${style}.ftl    # 多风格首页
12
├── channel/                  # 栏目页模板
13
│   ├── list.ftl              # 列表页
14
│   ├── list_pic.ftl          # 图片列表页
15
│   └── list_video.ftl        # 视频列表页
16
├── content/                  # 内容页模板
17
│   ├── detail.ftl            # 详情页
18
│   ├── detail_article.ftl    # 文章详情
19
│   ├── detail_pic.ftl        # 图片详情
20
│   └── detail_video.ftl      # 视频详情
21
├── search/                   # 搜索模板
22
│   ├── search.ftl            # 搜索结果页
23
│   └── search_form.ftl       # 搜索表单
24
├── error/                    # 错误页面
25
│   ├── 404.ftl
26
│   ├── 500.ftl
27
│   └── noPermission.ftl
28
└── special/                  # 专题模板
29
    └── topic_*.ftl

展开收起

博达后台的模板管理模块允许管理员在线编辑这些 .ftl 文件，修改后保存，下次访问时自动生效（如果开启了模板热加载）。

2.6 模板热加载#

FreeMarker 支持模板的热加载——修改模板文件后不需要重启服务器。实现原理：

1
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
2

3
// 关键配置：模板更新延迟
4
cfg.setTemplateUpdateDelayMilliseconds(0);
5
// 设置为 0 表示每次请求都检查模板是否更新
6
// 生产环境建议设置为 5000（5秒），减轻文件系统压力
7

8
// 使用文件系统加载器，而非类路径加载器
9
cfg.setDirectoryForTemplateLoading(new File("/path/to/templates"));
10
// 文件系统加载器才能感知文件变更
11

12
// 或者使用 ServletContext 加载器
13
cfg.setServletContextForTemplateLoading(servletContext, "/WEB-INF/templates");

当 setTemplateUpdateDelayMilliseconds(0) 时，每次调用 Configuration.getTemplate() 都会检查文件的最后修改时间。如果文件时间戳变了，FreeMarker 会重新解析模板文件，生成新的 Template 对象。

实际实现中，博达可能做了一层自己的模板缓存，但原理相同。

2.7 模板中的安全处理#

模板中直接输出用户输入的内容存在 XSS 风险。博达的处理方式：

1
<#-- 危险：直接输出，会执行 HTML 和 JS -->
2
${content.title}
3

4
<#-- 安全：使用内建函数进行 HTML 转义 -->
5
${content.title?html}
6

7
<#-- 富文本内容：需要不转义输出（但要在后端做 XSS 过滤） -->
8
${content.content?no_esc}

博达的后端在上传资料时会对富文本内容做 XSS 过滤，然后在前台模板中需要用 ?no_esc 输出富文本。这是一个需要特别注意的安全点——如果你在二次开发中修改了输出方式，一定要确保 XSS 过滤没有被绕过。

三、JSP/Servlet 实现层#

3.1 web.xml 中的核心配置#

博达的 web.xml 是整个应用的入口。以下是典型配置：

1
<?xml version="1.0" encoding="UTF-8"?>
2
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
5
         http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
6
         version="3.0">
7

8
    <display-name>Boda Website Group Platform</display-name>
9

10
    <!-- 字符编码过滤器 -->
11
    <filter>
12
        <filter-name>encodingFilter</filter-name>
13
        <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
14
        <init-param>
15
            <param-name>encoding</param-name>
16
            <param-value>UTF-8</param-value>
17
        </init-param>
18
        <init-param>
19
            <param-name>forceEncoding</param-name>
20
            <param-value>true</param-value>
21
        </init-param>
22
    </filter>
23

24
    <!-- 站点域名解析过滤器 -->
25
    <filter>
26
        <filter-name>siteFilter</filter-name>
27
        <filter-class>com.boda.web.filter.SiteFilter</filter-class>
28
    </filter>
29

30
    <!-- 登录认证过滤器 -->
31
    <filter>
32
        <filter-name>authFilter</filter-name>
33
        <filter-class>com.boda.web.filter.AuthFilter</filter-class>
34
    </filter>
35

36
    <!-- 访问日志过滤器 -->
37
    <filter>
38
        <filter-name>accessLogFilter</filter-name>
39
        <filter-class>com.boda.web.filter.AccessLogFilter</filter-class>
40
    </filter>
41

42
    <filter-mapping>
43
        <filter-name>encodingFilter</filter-name>
44
        <url-pattern>/*</url-pattern>
45
    </filter-mapping>
46
    <filter-mapping>
47
        <filter-name>siteFilter</filter-name>
48
        <url-pattern>/*</url-pattern>
49
    </filter-mapping>
50
    <filter-mapping>
51
        <filter-name>authFilter</filter-name>
52
        <url-pattern>/admin/*</url-pattern>
53
    </filter-mapping>
54
    <filter-mapping>
55
        <filter-name>accessLogFilter</filter-name>
56
        <url-pattern>/*</url-pattern>
57
    </filter-mapping>
58

59
    <!-- Spring 配置 -->
60
    <listener>
61
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
62
    </listener>
63
    <context-param>
64
        <param-name>contextConfigLocation</param-name>
65
        <param-value>classpath:spring/applicationContext-*.xml</param-value>
66
    </context-param>
67

68
    <!-- Spring MVC 前端控制器 -->
69
    <servlet>
70
        <servlet-name>springMVC</servlet-name>
71
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
72
        <init-param>
73
            <param-name>contextConfigLocation</param-name>
74
            <param-value>classpath:spring/springmvc-servlet.xml</param-value>
75
        </init-param>
76
        <load-on-startup>1</load-on-startup>
77
    </servlet>
78

79
    <!-- 静态页面访问 Servlet（处理已发布的 HTML） -->
80
    <servlet>
81
        <servlet-name>staticPageServlet</servlet-name>
82
        <servlet-class>com.boda.web.servlet.StaticPageServlet</servlet-class>
83
    </servlet>
84

85
    <!-- API Servlet -->
86
    <servlet>
87
        <servlet-name>apiServlet</servlet-name>
88
        <servlet-class>com.boda.web.servlet.ApiServlet</servlet-class>
89
    </servlet>
90

91
    <servlet-mapping>
92
        <servlet-name>springMVC</servlet-name>
93
        <url-pattern>/admin/*</url-pattern>
94
    </servlet-mapping>
95
    <servlet-mapping>
96
        <servlet-name>staticPageServlet</servlet-name>
97
        <url-pattern>*.html</url-pattern>
98
    </servlet-mapping>
99
    <servlet-mapping>
100
        <servlet-name>apiServlet</servlet-name>
101
        <url-pattern>/api/*</url-pattern>
102
    </servlet-mapping>
103

104
    <!-- 默认 Servlet（处理静态资源） -->
105
    <servlet-mapping>
106
        <servlet-name>default</servlet-name>
107
        <url-pattern>*.js</url-pattern>
108
        <url-pattern>*.css</url-pattern>
109
        <url-pattern>*.png</url-pattern>
110
        <url-pattern>*.jpg</url-pattern>
111
        <url-pattern>*.gif</url-pattern>
112
        <url-pattern>*.ico</url-pattern>
113
        <url-pattern>*.woff</url-pattern>
114
        <url-pattern>*.woff2</url-pattern>
115
    </servlet-mapping>
116

117
    <!-- Session 超时时间（分钟） -->
118
    <session-config>
119
        <session-timeout>30</session-timeout>
120
    </session-config>
121

122
    <!-- 欢迎页面 -->
123
    <welcome-file-list>
124
        <welcome-file>index.html</welcome-file>
125
        <welcome-file>index.jsp</welcome-file>
126
    </welcome-file-list>
127
</web-app>

展开收起

3.2 SiteFilter — 站点域名解析#

这是博达最核心的 Filter 之一。它负责根据请求的域名确定当前是哪个站点。

1
public class SiteFilter implements Filter {
2

3
    private SiteService siteService;
4

5
    @Override
6
    public void init(FilterConfig filterConfig) {
7
        siteService = SpringContextHolder.getBean(SiteService.class);
8
    }
9

10
    @Override
11
    public void doFilter(ServletRequest request, ServletResponse response,
12
                         FilterChain chain) throws IOException, ServletException {
13
        HttpServletRequest httpRequest = (HttpServletRequest) request;
14
        HttpServletResponse httpResponse = (HttpServletResponse) response;
15

16
        // 1. 从请求中提取域名
17
        String serverName = httpRequest.getServerName();
18
        // serverName 可能是 www.example.com 或 example.com
19

20
        // 2. 处理端口号（非 80 端口需要保留）
21
        int port = httpRequest.getServerPort();
22
        String domainKey = (port == 80 || port == 443)
23
            ? serverName
24
            : serverName + ":" + port;
25

26
        // 3. 从缓存或数据库中查找站点
27
        Site site = siteService.getSiteByDomain(domainKey);
28

29
        if (site == null) {
30
            // 尝试泛域名匹配 *.example.com
31
            site = siteService.matchWildcardDomain(serverName);
32
        }
33

34
        if (site == null) {
35
            // 找不到站点 → 使用默认站点
36
            site = siteService.getDefaultSite();
37
        }
38

39
        // 4. 将站点信息绑定到当前请求线程
40
        SiteContextHolder.setSite(site);
41

42
        // 5. 设置请求属性，后续 Servlet 和模板都能获取
43
        httpRequest.setAttribute("_site", site);
44
        httpRequest.setAttribute("_siteId", site.getId());
45

46
        try {
47
            chain.doFilter(request, response);
48
        } finally {
49
            // 6. 清理 ThreadLocal，防止内存泄漏
50
            SiteContextHolder.clear();
51
        }
52
    }
53
}

展开收起

SiteContextHolder 是一个 ThreadLocal 封装，确保在一次请求的完整链路中，所有代码都能获取到当前站点信息。

1
public class SiteContextHolder {
2
    private static final ThreadLocal<Site> siteHolder = new ThreadLocal<>();
3

4
    public static void setSite(Site site) {
5
        siteHolder.set(site);
6
    }
7

8
    public static Site getSite() {
9
        return siteHolder.get();
10
    }
11

12
    public static void clear() {
13
        siteHolder.remove();
14
    }
15
}

展开收起

3.3 页面分发核心逻辑#

当前台页面被访问时，StaticPageServlet 负责处理。它的核心逻辑如下：

1
public class StaticPageServlet extends HttpServlet {
2

3
    @Autowired
4
    private PublishEngine publishEngine;
5

6
    @Autowired
7
    private SiteService siteService;
8

9
    @Override
10
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
11
            throws ServletException, IOException {
12

13
        // 1. 获取站点信息
14
        Site site = SiteContextHolder.getSite();
15

16
        // 2. 解析请求路径
17
        String requestUri = request.getRequestURI();
18
        String contextPath = request.getContextPath();
19
        String relativePath = requestUri.substring(contextPath.length());
20

21
        // 3. 构建发布文件的路径
22
        // 发布目录结构: /publish/{siteId}/{relativePath}/index.html
23
        String publishPath = site.getPublishRoot() + relativePath;
24
        if (relativePath.endsWith("/")) {
25
            publishPath += "index.html";
26
        }
27

28
        File publishFile = new File(publishPath);
29

30
        // 4. 检查是否存在已发布的静态页面
31
        if (publishFile.exists() && !isPreviewMode(request)) {
32
            // 直接返回静态 HTML（性能最优）
33
            response.setContentType("text/html;charset=UTF-8");
34
            response.setHeader("X-Cache", "HIT");
35
            FileUtils.copyFile(publishFile, response.getOutputStream());
36
            return;
37
        }
38

39
        // 5. 动态渲染（预览模式 或 页面未发布）
40
        response.setHeader("X-Cache", "DYNAMIC");
41

42
        // 5.1 解析当前访问的是栏目还是内容
43
        PageType pageType = resolvePageType(site, relativePath);
44
        // pageType 可能是: INDEX, CHANNEL_LIST, CONTENT_DETAIL, SEARCH, SPECIAL
45

46
        // 5.2 构建数据模型
47
        Map<String, Object> dataModel = buildDataModel(request, site, pageType, relativePath);
48

49
        // 5.3 获取对应的模板
50
        String templatePath = getTemplatePath(site, pageType, relativePath);
51
        // 例如: /channel/list.ftl, /content/detail.ftl
52

53
        // 5.4 使用 FreeMarker 渲染
54
        try {
55
            Configuration cfg = FreeMarkerConfigurer.getConfiguration();
56
            Template template = cfg.getTemplate(templatePath);
57
            template.process(dataModel, response.getWriter());
58
        } catch (TemplateException e) {
59
            throw new ServletException("Template processing error", e);
60
        }
61
    }
62

63
    /**
64
     * 解析页面类型
65
     * 例如:
66
     *   / → INDEX（首页）
67
     *   /xx/ → CHANNEL_LIST（栏目列表页）
68
     *   /xx/123.html → CONTENT_DETAIL（内容详情页）
69
     */
70
    private PageType resolvePageType(Site site, String path) {
71
        if (path == null || path.equals("/") || path.equals("/index.html")) {
72
            return PageType.INDEX;
73
        }
74

75
        // 从站点映射中查找匹配的栏目
76
        Channel channel = siteService.matchChannel(site.getId(), path);
77
        if (channel != null) {
78
            if (channel.getType() == ChannelType.LINK) {
79
                return PageType.LINK_REDIRECT;
80
            }
81
            return PageType.CHANNEL_LIST;
82
        }
83

84
        // 检查是否是内容详情页（路径包含数字 ID）
85
        Pattern pattern = Pattern.compile(".*/(\\d+)\\.html$");
86
        Matcher matcher = pattern.matcher(path);
87
        if (matcher.matches()) {
88
            return PageType.CONTENT_DETAIL;
89
        }
90

91
        // 检查是否是搜索页面
92
        if (path.contains("/search/")) {
93
            return PageType.SEARCH;
94
        }
95

96
        return PageType.ERROR_404;
97
    }
98
}

展开收起

3.4 后台管理 JSP 页面#

博达的后台管理界面使用 JSP + JSTL 实现。典型的后台页面结构如下：

1
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
2
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
3
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
4
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
5
<!DOCTYPE html>
6
<html>
7
<head>
8
    <meta charset="UTF-8">
9
    <title>栏目管理 - ${site.name}</title>
10
    <link rel="stylesheet" href="${pageContext.request.contextPath}/admin/css/admin.css">
11
</head>
12
<body>
13
    <div class="container">
14
        <!-- 侧边栏 -->
15
        <jsp:include page="/admin/_inc/sidebar.jsp"/>
16

17
        <!-- 主内容 -->
18
        <div class="main-content">
19
            <div class="page-header">
20
                <h3>栏目管理</h3>
21
                <div class="breadcrumb">
22
                    <a href="${pageContext.request.contextPath}/admin/">首页</a> &gt;
23
                    栏目管理
24
                </div>
25
            </div>
26

27
            <!-- 操作按钮 -->
28
            <div class="toolbar">
29
                <a href="${pageContext.request.contextPath}/admin/channel/add"
30
                   class="btn btn-primary">新增栏目</a>
31
                <a href="${pageContext.request.contextPath}/admin/channel/sort"
32
                   class="btn btn-default">排序</a>
33
                <button onclick="batchDelete()" class="btn btn-danger">批量删除</button>
34
            </div>
35

36
            <!-- 栏目树表格 -->
37
            <table class="table table-tree">
38
                <thead>
39
                    <tr>
40
                        <th style="width:30px"><input type="checkbox" id="selectAll"></th>
41
                        <th>栏目名称</th>
42
                        <th>类型</th>
43
                        <th>状态</th>
44
                        <th>访问路径</th>
45
                        <th>模板</th>
46
                        <th>操作</th>
47
                    </tr>
48
                </thead>
49
                <tbody>
50
                    <c:forEach items="${channelList}" var="ch">
51
                        <tr data-id="${ch.id}" data-pid="${ch.parentId}"
52
                            style="padding-left:${ch.depth * 20}px">
53
                            <td><input type="checkbox" name="ids" value="${ch.id}"></td>
54
                            <td>
55
                                <span class="tree-indent" style="display:inline-block;
56
                                      width:${ch.depth * 20}px"></span>
57
                                <c:if test="${ch.hasChildren}">
58
                                    <span class="tree-toggle expanded"
59
                                          onclick="toggleTree(this)"></span>
60
                                </c:if>
61
                                ${ch.name}
62
                                <c:if test="${ch.isTop}">
63
                                    <span class="badge badge-primary">顶部</span>
64
                                </c:if>
65
                            </td>
66
                            <td>${ch.type.displayName}</td>
67
                            <td>
68
                                <c:choose>
69
                                    <c:when test="${ch.status == 'published'}">
70
                                        <span class="label label-success">已发布</span>
71
                                    </c:when>
72
                                    <c:when test="${ch.status == 'draft'}">
73
                                        <span class="label label-warning">草稿</span>
74
                                    </c:when>
75
                                    <c:otherwise>
76
                                        <span class="label label-default">${ch.status}</span>
77
                                    </c:otherwise>
78
                                </c:choose>
79
                            </td>
80
                            <td><code>${ch.path}</code></td>
81
                            <td>${ch.listTemplate}</td>
82
                            <td>
83
                                <a href="${pageContext.request.contextPath}/admin/channel/edit?id=${ch.id}">编辑</a>
84
                                <a href="${pageContext.request.contextPath}/admin/content/list?channelId=${ch.id}">内容</a>
85
                                <a href="${pageContext.request.contextPath}/admin/publish?channelId=${ch.id}">发布</a>
86
                                <a href="javascript:void(0)" onclick="deleteChannel(${ch.id})">删除</a>
87
                            </td>
88
                        </tr>
89
                    </c:forEach>
90
                </tbody>
91
            </table>
92
        </div>
93
    </div>
94

95
    <script src="${pageContext.request.contextPath}/admin/js/jquery.min.js"></script>
96
    <script src="${pageContext.request.contextPath}/admin/js/admin.js"></script>
97
    <script>
98
        function toggleTree(el) {
99
            $(el).toggleClass('expanded collapsed');
100
            var tr = $(el).closest('tr');
101
            var id = tr.data('id');
102
            $('tr[data-pid="' + id + '"]').toggle();
103
        }
104

105
        function deleteChannel(id) {
106
            if (!confirm('确定删除该栏目及其所有子栏目和内容？')) return;
107
            $.post('${pageContext.request.contextPath}/admin/channel/delete', {id: id},
108
                function(res) {
109
                    if (res.code === 200) {
110
                        location.reload();
111
                    } else {
112
                        alert(res.message);
113
                    }
114
                });
115
        }
116
    </script>
117
</body>
118
</html>

展开收起

四、栏目管理#

4.1 栏目数据模型#

栏目是博达内容组织的核心骨架。在数据库中，栏目的表结构大致如下：

1
CREATE TABLE `cms_channel` (
2
  `id`          INT           NOT NULL AUTO_INCREMENT   COMMENT '栏目ID',
3
  `site_id`     INT           NOT NULL                   COMMENT '所属站点ID',
4
  `parent_id`   INT           DEFAULT 0                  COMMENT '父栏目ID，0表示顶级',
5
  `name`        VARCHAR(100)  NOT NULL                   COMMENT '栏目名称',
6
  `path`        VARCHAR(200)  NOT NULL                   COMMENT '访问路径（URL中的路径段）',
7
  `sort`        INT           DEFAULT 0                  COMMENT '排序号',
8
  `depth`       INT           DEFAULT 1                  COMMENT '层级深度',
9
  `type`        VARCHAR(20)   DEFAULT 'channel'           COMMENT '栏目类型',
10
  `status`      VARCHAR(20)   DEFAULT 'draft'             COMMENT '状态',
11
  `list_template`    VARCHAR(200) DEFAULT ''              COMMENT '列表页模板路径',
12
  `detail_template`  VARCHAR(200) DEFAULT ''              COMMENT '详情页模板路径',
13
  `link_url`    VARCHAR(500)  DEFAULT ''                  COMMENT '外部链接URL',
14
  `keywords`    VARCHAR(200)  DEFAULT ''                  COMMENT 'SEO关键词',
15
  `description` VARCHAR(500)  DEFAULT ''                  COMMENT 'SEO描述',
16
  `is_top`      TINYINT       DEFAULT 0                  COMMENT '是否顶部导航',
17
  `is_bottom`   TINYINT       DEFAULT 0                  COMMENT '是否底部导航',
18
  `is_show`     TINYINT       DEFAULT 1                  COMMENT '是否显示',
19
  `allow_comment` TINYINT     DEFAULT 1                  COMMENT '是否允许评论',
20
  `page_size`   INT           DEFAULT 20                 COMMENT '列表页每页条数',
21
  `roles`       VARCHAR(500)  DEFAULT ''                  COMMENT '可访问角色ID列表',
22
  `create_by`   INT           DEFAULT 0                  COMMENT '创建人',
23
  `create_time` DATETIME      DEFAULT CURRENT_TIMESTAMP   COMMENT '创建时间',
24
  `update_time` DATETIME      DEFAULT CURRENT_TIMESTAMP
25
                              ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
26
  PRIMARY KEY (`id`),
27
  KEY `idx_site_id` (`site_id`),
28
  KEY `idx_parent_id` (`parent_id`),
29
  KEY `idx_path` (`site_id`, `path`)
30
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='栏目表';

展开收起

4.2 栏目树结构的实现#

博达的栏目是典型的树形结构，使用 parent_id 自关联。查询子树时，最简单的做法是递归查询，但在数据量大的场景下性能不好。博达的优化手段：

方法一：一次性加载整棵树（适用于栏目数少于 500 的场景）

1
public class ChannelServiceImpl implements ChannelService {
2

3
    public List<ChannelTreeNode> getChannelTree(Integer siteId) {
4
        // 1. 一次性查出该站点所有栏目
5
        List<Channel> allChannels = channelDao.selectBySiteId(siteId);
6

7
        // 2. 在内存中构建树
8
        Map<Integer, List<Channel>> parentMap = allChannels.stream()
9
            .collect(Collectors.groupingBy(Channel::getParentId));
10

11
        // 3. 从根节点开始递归构建树
12
        List<ChannelTreeNode> tree = buildTree(parentMap, 0, 1);
13
        return tree;
14
    }
15

16
    private List<ChannelTreeNode> buildTree(
17
            Map<Integer, List<Channel>> parentMap,
18
            Integer parentId, int depth) {
19
        List<Channel> children = parentMap.getOrDefault(parentId, Collections.emptyList());
20
        List<ChannelTreeNode> nodes = new ArrayList<>();
21

22
        for (Channel ch : children) {
23
            ChannelTreeNode node = new ChannelTreeNode();
24
            node.setId(ch.getId());
25
            node.setName(ch.getName());
26
            node.setDepth(depth);
27
            node.setHasChildren(parentMap.containsKey(ch.getId()));
28
            // 递归构建子节点
29
            node.setChildren(buildTree(parentMap, ch.getId(), depth + 1));
30
            nodes.add(node);
31
        }
32

33
        // 按 sort 字段排序
34
        nodes.sort(Comparator.comparingInt(ChannelTreeNode::getSort));
35
        return nodes;
36
    }
37
}

展开收起

方法二：使用闭包表（Closure Table）适用于大规模栏目的场景

闭包表是一种用空间换时间的树结构方案。额外建一张表记录所有祖先-后代关系：

1
CREATE TABLE `cms_channel_closure` (
2
  `ancestor`   INT NOT NULL COMMENT '祖先节点ID',
3
  `descendant` INT NOT NULL COMMENT '后代节点ID',
4
  `depth`      INT NOT NULL COMMENT '层级差（0表示自身）',
5
  PRIMARY KEY (`ancestor`, `descendant`),
6
  KEY `idx_descendant` (`descendant`)
7
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='栏目闭包表';

查询某个栏目下的所有子栏目（任意层级）：

1
-- 获取 /about/ 栏目下的所有子栏目（包括间接子栏目）
2
SELECT c.* FROM cms_channel c
3
JOIN cms_channel_closure cl ON c.id = cl.descendant
4
WHERE cl.ancestor = (SELECT id FROM cms_channel WHERE path = '/about/' AND site_id = ?)
5
  AND cl.depth > 0
6
ORDER BY c.sort;

查询某个栏目的所有父栏目（面包屑导航）：

1
-- 获取当前栏目的所有父栏目（用于面包屑）
2
SELECT c.* FROM cms_channel c
3
JOIN cms_channel_closure cl ON c.id = cl.ancestor
4
WHERE cl.descendant = ?
5
ORDER BY cl.depth DESC;

4.3 栏目类型#

博达的栏目有多种类型，每种类型的行为不同：

类型	说明	处理逻辑
普通栏目	有列表页和内容页	列表页展示内容列表，详情页展示单条内容
单页栏目	只有一个页面（如”关于我们”）	列表页即详情页，不需要内容列表
外部链接	跳转到外部 URL	访问时直接 302 重定向
内部跳转	跳转到站内其他栏目	访问时直接 302 跳转
聚合栏目	聚合多个子栏目的内容	列表页展示所有子栏目的最新内容

4.4 栏目路径与 URL 生成#

每个栏目有一个 path 字段，用于生成 URL。路径的组装规则：

1
public String buildChannelUrl(Site site, Channel channel) {
2
    // 如果是外部链接，直接返回
3
    if (channel.getType() == ChannelType.LINK) {
4
        return channel.getLinkUrl();
5
    }
6

7
    // 如果是内部跳转，递归获取目标栏目 URL
8
    if (channel.getType() == ChannelType.REDIRECT) {
9
        Channel target = channelDao.selectById(channel.getRedirectId());
10
        return buildChannelUrl(site, target);
11
    }
12

13
    // 普通栏目：递归从根节点组装路径
14
    StringBuilder path = new StringBuilder(channel.getPath());
15
    Integer parentId = channel.getParentId();
16

17
    while (parentId != null && parentId != 0) {
18
        Channel parent = channelDao.selectById(parentId);
19
        if (parent == null) break;
20
        path.insert(0, parent.getPath().endsWith("/")
21
            ? parent.getPath() : parent.getPath() + "/");
22
        parentId = parent.getParentId();
23
    }
24

25
    // 最终 URL: /parent/child/index.html
26
    String fullPath = path.toString();
27
    if (!fullPath.endsWith("/")) {
28
        fullPath += "/";
29
    }
30
    fullPath += "index.html";
31

32
    return site.getDomain() + fullPath;
33
}

展开收起

4.5 栏目创建流程#

在博达后台创建一个栏目的完整流程：

1
1. 管理员进入"栏目管理" → 点击"新增栏目"
2
       ↓
3
2. JSP 页面加载 → Controller 返回表单页面
4
       ↓
5
3. 管理员填写表单：
6
   - 栏目名称（必填）
7
   - 父栏目（默认为顶级）
8
   - 访问路径（自动生成或手动填写）
9
   - 栏目类型（普通/单页/链接/跳转/聚合）
10
   - 列表模板、详情模板
11
   - SEO 信息
12
   - 权限设置
13
       ↓
14
4. 提交表单 → POST /admin/channel/add
15
       ↓
16
5. Controller 接收参数
17
   ↓
18
6. Service 层校验：
19
   - 名称是否重复
20
   - 路径是否与其他栏目冲突
21
   - 父栏目是否存在
22
   - 模板文件是否存在
23
       ↓
24
7. DAO 层插入数据库
25
   ↓
26
8. 更新闭包表（如果使用）
27
   ↓
28
9. 记录操作日志
29
   ↓
30
10. 返回成功 → 页面刷新显示新栏目

展开收起

对应的 Controller 代码大致如下：

1
@Controller
2
@RequestMapping("/admin/channel")
3
public class ChannelController {
4

5
    @Autowired
6
    private ChannelService channelService;
7

8
    @Autowired
9
    private LogService logService;
10

11
    @GetMapping("/add")
12
    public String addForm(Model model) {
13
        Site site = SiteContextHolder.getSite();
14
        model.addAttribute("site", site);
15
        model.addAttribute("channelTree", channelService.getChannelTree(site.getId()));
16
        model.addAttribute("templateList", templateService.getTemplates(site.getId()));
17
        return "admin/channel/add";
18
    }
19

20
    @PostMapping("/add")
21
    @ResponseBody
22
    public Result add(@Validated ChannelAddDTO dto, BindingResult result) {
23
        if (result.hasErrors()) {
24
            return Result.error(result.getAllErrors().get(0).getDefaultMessage());
25
        }
26

27
        Site site = SiteContextHolder.getSite();
28
        dto.setSiteId(site.getId());
29

30
        try {
31
            Channel channel = channelService.addChannel(dto);
32
            logService.log(LogType.CHANNEL, "新增栏目: " + channel.getName(),
33
                          channel.getId());
34
            return Result.success(channel);
35
        } catch (BusinessException e) {
36
            return Result.error(e.getMessage());
37
        }
38
    }
39
}

展开收起

五、资料库（内容管理）#

5.1 资料数据模型#

资料（内容）是博达中最核心的业务数据。它的表结构反映了博达设计的核心思路——内容与展现分离。

1
CREATE TABLE `cms_content` (
2
  `id`            INT           NOT NULL AUTO_INCREMENT   COMMENT '资料ID',
3
  `site_id`       INT           NOT NULL                   COMMENT '所属站点ID',
4
  `channel_id`    INT           NOT NULL                   COMMENT '所属栏目ID',
5
  `title`         VARCHAR(300)  NOT NULL                   COMMENT '标题',
6
  `sub_title`     VARCHAR(300)  DEFAULT ''                  COMMENT '副标题',
7
  `short_title`   VARCHAR(100)  DEFAULT ''                  COMMENT '短标题',
8
  `keywords`      VARCHAR(200)  DEFAULT ''                  COMMENT '关键词',
9
  `summary`       VARCHAR(1000) DEFAULT ''                  COMMENT '摘要',
10
  `author`        VARCHAR(100)  DEFAULT ''                  COMMENT '作者',
11
  `source`        VARCHAR(200)  DEFAULT ''                  COMMENT '来源',
12
  `content`       MEDIUMTEXT                               COMMENT '正文内容（HTML格式）',
13
  `status`        VARCHAR(20)   DEFAULT 'draft'             COMMENT '状态',
14
  `sort`          INT           DEFAULT 0                  COMMENT '排序号',
15
  `is_top`        TINYINT       DEFAULT 0                  COMMENT '是否置顶',
16
  `is_recommend`  TINYINT       DEFAULT 0                  COMMENT '是否推荐',
17
  `is_slide`      TINYINT       DEFAULT 0                  COMMENT '是否轮播',
18
  `is_bold`       TINYINT       DEFAULT 0                  COMMENT '标题是否加粗',
19
  `link_url`      VARCHAR(500)  DEFAULT ''                  COMMENT '跳转链接',
20
  `publish_date`  DATETIME      DEFAULT NULL               COMMENT '发布时间',
21
  `create_by`     INT           DEFAULT 0                  COMMENT '创建人',
22
  `create_time`   DATETIME      DEFAULT CURRENT_TIMESTAMP   COMMENT '创建时间',
23
  `update_time`   DATETIME      DEFAULT CURRENT_TIMESTAMP
24
                                ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
25
  PRIMARY KEY (`id`),
26
  KEY `idx_site_channel` (`site_id`, `channel_id`),
27
  KEY `idx_publish_date` (`publish_date`),
28
  KEY `idx_status` (`status`),
29
  FULLTEXT KEY `ft_title_content` (`title`, `content`)
30
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='资料表';

展开收起

5.2 扩展字段体系#

博达支持自定义扩展字段，这是通过额外的扩展属性表实现的：

1
CREATE TABLE `cms_content_attr` (
2
  `id`         INT           NOT NULL AUTO_INCREMENT,
3
  `content_id` INT           NOT NULL        COMMENT '资料ID',
4
  `attr_name`  VARCHAR(100)  NOT NULL        COMMENT '属性名',
5
  `attr_value` TEXT                           COMMENT '属性值',
6
  `attr_type`  VARCHAR(20)   DEFAULT 'text'  COMMENT '属性类型',
7
  `sort`       INT           DEFAULT 0,
8
  PRIMARY KEY (`id`),
9
  KEY `idx_content_id` (`content_id`)
10
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='资料扩展属性表';

扩展字段的配置存储在系统配置表或 XML 配置中：

1
<!-- 栏目扩展字段配置示例 -->
2
<extFields>
3
    <field name="fileNo" displayName="发文字号" type="text"/>
4
    <field name="validDate" displayName="有效期" type="date"/>
5
    <field name="attachment" displayName="附件" type="file"/>
6
    <field name="relatedNews" displayName="相关新闻" type="multiText"/>
7
</extFields>

5.3 资料与附件管理#

博达的附件管理涉及文件和数据库两部分。附件上传后存储在文件系统中，同时在数据库中记录元数据：

1
CREATE TABLE `cms_attachment` (
2
  `id`           INT           NOT NULL AUTO_INCREMENT,
3
  `content_id`   INT           DEFAULT 0        COMMENT '关联资料ID',
4
  `file_name`    VARCHAR(300)  NOT NULL          COMMENT '原始文件名',
5
  `file_path`    VARCHAR(500)  NOT NULL          COMMENT '存储路径',
6
  `file_size`    BIGINT        DEFAULT 0         COMMENT '文件大小（字节）',
7
  `file_type`    VARCHAR(50)   DEFAULT ''        COMMENT '文件MIME类型',
8
  `suffix`       VARCHAR(10)   DEFAULT ''        COMMENT '文件后缀',
9
  `is_image`     TINYINT       DEFAULT 0         COMMENT '是否图片',
10
  `width`        INT           DEFAULT 0         COMMENT '图片宽度',
11
  `height`       INT           DEFAULT 0         COMMENT '图片高度',
12
  `download_count` INT        DEFAULT 0          COMMENT '下载次数',
13
  `create_time`  DATETIME      DEFAULT CURRENT_TIMESTAMP,
14
  PRIMARY KEY (`id`),
15
  KEY `idx_content_id` (`content_id`)
16
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='附件表';

展开收起

附件的存储路径生成规则：

1
public String generateFilePath(String originalFileName, Integer siteId) {
2
    // 按日期分目录，避免单目录文件过多
3
    String datePath = new SimpleDateFormat("yyyy/MM/dd").format(new Date());
4

5
    // 生成唯一文件名
6
    String uuid = UUID.randomUUID().toString().replace("-", "");
7
    String suffix = originalFileName.substring(originalFileName.lastIndexOf("."));
8

9
    // 最终路径: /uploads/{siteId}/{datePath}/{uuid}{suffix}
10
    return String.format("/uploads/%d/%s/%s%s", siteId, datePath, uuid, suffix);
11
}

5.4 资料发布状态机#

资料的状态流转：

1
                ┌──────────┐
2
                │   草稿    │
3
                └────┬─────┘
4
                     │ 提交
5
                     ↓
6
                ┌──────────┐
7
          ┌─────│  待审核   │─────┐
8
          │     └────┬─────┘     │
9
          │          │ 审核通过   │ 审核驳回
10
          │          ↓           │
11
          │     ┌──────────┐     │
12
          │     │  已通过   │     │
13
          │     └────┬─────┘     │
14
          │          │ 发布       │
15
          │          ↓           │
16
          │     ┌──────────┐     │
17
          │     │  已发布   │─────┘
18
          │     └────┬─────┘
19
          │          │ 取消发布
20
          │          ↓
21
          │     ┌──────────┐
22
          └─────│  已下架   │
23
                └──────────┘

展开收起

状态管理的 Service 层实现：

1
@Service
2
public class ContentServiceImpl implements ContentService {
3

4
    // 审核内容
5
    @Transactional
6
    public void approve(Integer contentId, Integer reviewerId) {
7
        Content content = contentDao.selectById(contentId);
8
        if (content.getStatus() != ContentStatus.PENDING) {
9
            throw new BusinessException("当前状态不允许审核");
10
        }
11

12
        Content update = new Content();
13
        update.setId(contentId);
14
        update.setStatus(ContentStatus.APPROVED);
15
        update.setReviewerId(reviewerId);
16
        update.setReviewTime(new Date());
17
        contentDao.update(update);
18
    }
19

20
    // 发布内容
21
    @Transactional
22
    public void publish(Integer contentId, Integer publisherId) {
23
        Content content = contentDao.selectById(contentId);
24
        if (content.getStatus() != ContentStatus.APPROVED) {
25
            throw new BusinessException("只有已审核的内容才能发布");
26
        }
27

28
        Content update = new Content();
29
        update.setId(contentId);
30
        update.setStatus(ContentStatus.PUBLISHED);
31
        update.setPublisherId(publisherId);
32
        update.setPublishDate(new Date());
33
        contentDao.update(update);
34

35
        // 触发发布事件 → 异步生成静态页面
36
        publishEngine.publishContent(content.getSiteId(),
37
                                     content.getChannelId(), contentId);
38
    }
39
}

展开收起

5.5 资料列表查询#

博达的列表查询支持多种筛选和排序条件，核心 DAO 层使用 MyBatis 动态 SQL：

1
<select id="selectContentList" resultMap="contentMap">
2
    SELECT * FROM cms_content
3
    <where>
4
        <if test="siteId != null">
5
            AND site_id = #{siteId}
6
        </if>
7
        <if test="channelIds != null and channelIds.size > 0">
8
            AND channel_id IN
9
            <foreach collection="channelIds" item="id" open="(" separator="," close=")">
10
                #{id}
11
            </foreach>
12
        </if>
13
        <if test="status != null">
14
            AND status = #{status}
15
        </if>
16
        <if test="keyword != null and keyword != ''">
17
            AND (title LIKE CONCAT('%', #{keyword}, '%')
18
                 OR summary LIKE CONCAT('%', #{keyword}, '%'))
19
        </if>
20
        <if test="startDate != null">
21
            AND publish_date &gt;= #{startDate}
22
        </if>
23
        <if test="endDate != null">
24
            AND publish_date &lt;= #{endDate}
25
        </if>
26
        <if test="isTop != null">
27
            AND is_top = #{isTop}
28
        </if>
29
        <if test="isRecommend != null">
30
            AND is_recommend = #{isRecommend}
31
        </if>
32
    </where>
33
    ORDER BY
34
        is_top DESC,      <!-- 置顶优先 -->
35
        sort ASC,         <!-- 排序号 -->
36
        publish_date DESC <!-- 最新优先 -->
37
    LIMIT #{offset}, #{pageSize}
38
</select>

展开收起

六、发布引擎#

发布引擎是博达最核心的模块。它负责将模板和数据模型合并，生成静态 HTML 文件。

6.1 发布模式#

博达支持两种发布模式：

模式	触发条件	性能	使用场景
全量发布	手动触发、站点初始化	慢（全站重新生成）	更换模板、初始化站点
增量发布	内容审核通过、模板修改	快（只发布变更部分）	日常内容更新
定时发布	Cron 表达式	取决于发布量	定时生效的内容
一键发布	手动点击”发布”	中	管理员主动触发

6.2 发布引擎核心流程#

1
@Component
2
public class PublishEngine {
3

4
    private static final Logger log = LoggerFactory.getLogger(PublishEngine.class);
5

6
    @Autowired
7
    private Configuration freemarkerConfig;
8

9
    @Autowired
10
    private ChannelService channelService;
11

12
    @Autowired
13
    private ContentService contentService;
14

15
    @Autowired
16
    private SiteService siteService;
17

18
    private final ExecutorService publishExecutor =
19
        Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors() * 2);
20

21
    /**
22
     * 全量发布站点
23
     */
24
    public void fullPublish(Integer siteId) {
25
        Site site = siteService.getById(siteId);
26
        log.info("开始全量发布站点: {} (ID: {})", site.getName(), siteId);
27

28
        // 1. 清理旧的发布目录
29
        File publishDir = new File(site.getPublishRoot());
30
        FileUtils.deleteQuietly(publishDir);
31

32
        // 2. 获取站点所有栏目
33
        List<Channel> allChannels = channelService.getAllChannels(siteId);
34

35
        // 3. 发布首页
36
        publishIndex(site);
37

38
        // 4. 发布每个栏目的列表页
39
        for (Channel channel : allChannels) {
40
            publishChannelList(site, channel, 1); // 第1页
41
        }
42

43
        // 5. 发布每个已发布内容的详情页
44
        List<Content> publishedContents = contentService.getPublishedContents(siteId);
45
        for (Content content : publishedContents) {
46
            publishContentDetail(site, content);
47
        }
48

49
        // 6. 发布全局资源（CSS、JS、全局导航等）
50
        publishGlobalResources(site);
51

52
        log.info("全量发布完成: {} (ID: {})", site.getName(), siteId);
53
    }
54

55
    /**
56
     * 增量发布单条内容
57
     */
58
    public void publishContent(Integer siteId, Integer channelId, Integer contentId) {
59
        Site site = siteService.getById(siteId);
60
        Content content = contentService.getById(contentId);
61

62
        // 1. 发布内容详情页
63
        publishContentDetail(site, content);
64

65
        // 2. 重新发布所属栏目的列表页（列表页内容变了）
66
        Channel channel = channelService.getById(channelId);
67
        int totalPages = calculateTotalPages(site, channel);
68
        for (int page = 1; page <= totalPages; page++) {
69
            publishChannelList(site, channel, page);
70
        }
71

72
        // 3. 如果该栏目在首页有推荐，重新发布首页
73
        if (content.getIsRecommend() || content.getIsSlide()) {
74
            publishIndex(site);
75
        }
76

77
        // 4. 如果该栏目是顶级栏目，重新发布全局导航
78
        if (channel.getParentId() == 0) {
79
            publishGlobalResources(site);
80
        }
81

82
        log.info("增量发布完成: contentId={}", contentId);
83
    }
84

85
    /**
86
     * 发布首页
87
     */
88
    private void publishIndex(Site site) {
89
        try {
90
            // 1. 构建数据模型
91
            Map<String, Object> dataModel = new HashMap<>();
92
            dataModel.put("site", site);
93
            dataModel.put("channels", channelService.getTopLevelChannels(site.getId()));
94
            dataModel.put("recommendContents",
95
                contentService.getRecommendContents(site.getId(), 10));
96
            dataModel.put("slideContents",
97
                contentService.getSlideContents(site.getId(), 5));
98

99
            // 2. 获取首页模板
100
            Template template = freemarkerConfig.getTemplate("/index/index.ftl");
101

102
            // 3. 渲染并写入文件
103
            String outputPath = site.getPublishRoot() + "/index.html";
104
            File outputFile = new File(outputPath);
105
            FileUtils.forceMkdirParent(outputFile);
106

107
            try (Writer writer = new BufferedWriter(
108
                    new OutputStreamWriter(new FileOutputStream(outputFile), "UTF-8"))) {
109
                template.process(dataModel, writer);
110
            }
111

112
        } catch (Exception e) {
113
            log.error("发布首页失败: siteId={}", site.getId(), e);
114
        }
115
    }
116

117
    /**
118
     * 发布栏目列表页
119
     */
120
    private void publishChannelList(Site site, Channel channel, int pageNo) {
121
        try {
122
            // 1. 构建数据模型
123
            Map<String, Object> dataModel = new HashMap<>();
124
            dataModel.put("site", site);
125
            dataModel.put("channel", channel);
126
            dataModel.put("breadcrumb", channelService.getBreadcrumb(channel.getId()));
127

128
            // 2. 查询该栏目下的内容列表
129
            PageResult<Content> pageResult = contentService.getContentPage(
130
                site.getId(), channel.getId(), pageNo, channel.getPageSize());
131
            dataModel.put("contentList", pageResult.getList());
132
            dataModel.put("pageNo", pageNo);
133
            dataModel.put("totalPages", pageResult.getTotalPages());
134

135
            // 3. 获取列表页模板
136
            String templatePath = channel.getListTemplate();
137
            if (StringUtils.isEmpty(templatePath)) {
138
                templatePath = "/channel/list.ftl";
139
            }
140
            Template template = freemarkerConfig.getTemplate(templatePath);
141

142
            // 4. 确定输出路径
143
            // 第1页: /channelPath/index.html
144
            // 第N页: /channelPath/index_{N}.html
145
            String outputDir = site.getPublishRoot() + channel.getFullPath();
146
            String fileName = (pageNo == 1) ? "index.html" : "index_" + pageNo + ".html";
147
            File outputFile = new File(outputDir, fileName);
148
            FileUtils.forceMkdirParent(outputFile);
149

150
            // 5. 渲染
151
            try (Writer writer = new BufferedWriter(
152
                    new OutputStreamWriter(new FileOutputStream(outputFile), "UTF-8"))) {
153
                template.process(dataModel, writer);
154
            }
155

156
        } catch (Exception e) {
157
            log.error("发布栏目列表页失败: channelId={}, page={}",
158
                      channel.getId(), pageNo, e);
159
        }
160
    }
161

162
    /**
163
     * 发布内容详情页
164
     */
165
    private void publishContentDetail(Site site, Content content) {
166
        try {
167
            // 1. 构建数据模型
168
            Map<String, Object> dataModel = new HashMap<>();
169
            dataModel.put("site", site);
170
            dataModel.put("content", content);
171
            dataModel.put("channel", channelService.getById(content.getChannelId()));
172
            dataModel.put("breadcrumb",
173
                channelService.getBreadcrumb(content.getChannelId()));
174
            dataModel.put("attachments",
175
                attachmentService.getByContentId(content.getId()));
176
            dataModel.put("prevContent",
177
                contentService.getPrevContent(content.getId()));
178
            dataModel.put("nextContent",
179
                contentService.getNextContent(content.getId()));
180

181
            // 2. 获取详情页模板
182
            Channel channel = channelService.getById(content.getChannelId());
183
            String templatePath = channel.getDetailTemplate();
184
            if (StringUtils.isEmpty(templatePath)) {
185
                templatePath = "/content/detail.ftl";
186
            }
187
            Template template = freemarkerConfig.getTemplate(templatePath);
188

189
            // 3. 输出路径: /channelPath/contentId.html
190
            String outputDir = site.getPublishRoot() + channel.getFullPath();
191
            File outputFile = new File(outputDir, content.getId() + ".html");
192
            FileUtils.forceMkdirParent(outputFile);
193

194
            // 4. 渲染
195
            try (Writer writer = new BufferedWriter(
196
                    new OutputStreamWriter(new FileOutputStream(outputFile), "UTF-8"))) {
197
                template.process(dataModel, writer);
198
            }
199

200
        } catch (Exception e) {
201
            log.error("发布内容详情页失败: contentId={}", content.getId(), e);
202
        }
203
    }
204
}

展开收起

6.3 并发发布与性能优化#

全量发布时，博达使用线程池并发渲染，大幅提升发布速度：

1
public void concurrentPublish(Site site, List<Channel> channels, List<Content> contents) {
2
    CountDownLatch latch = new CountDownLatch(
3
        1 + channels.size() + contents.size());
4

5
    // 并发发布首页
6
    publishExecutor.submit(() -> {
7
        try { publishIndex(site); }
8
        finally { latch.countDown(); }
9
    });
10

11
    // 并发发布所有栏目列表页
12
    for (Channel channel : channels) {
13
        publishExecutor.submit(() -> {
14
            try {
15
                int totalPages = calculateTotalPages(site, channel);
16
                for (int page = 1; page <= totalPages; page++) {
17
                    publishChannelList(site, channel, page);
18
                }
19
            } finally {
20
                latch.countDown();
21
            }
22
        });
23
    }
24

25
    // 并发发布所有内容详情页
26
    for (Content content : contents) {
27
        publishExecutor.submit(() -> {
28
            try { publishContentDetail(site, content); }
29
            finally { latch.countDown(); }
30
        });
31
    }
32

33
    try {
34
        // 等待所有发布任务完成（最多30分钟）
35
        latch.await(30, TimeUnit.MINUTES);
36
    } catch (InterruptedException e) {
37
        Thread.currentThread().interrupt();
38
        log.error("发布被中断");
39
    }
40
}

展开收起

6.4 发布队列与异步处理#

在用户触发发布操作时，发布任务进入队列异步执行，避免用户等待：

1
@Component
2
public class PublishQueue {
3

4
    private final BlockingQueue<PublishTask> queue = new LinkedBlockingQueue<>(1000);
5
    private volatile boolean running = true;
6

7
    @PostConstruct
8
    public void init() {
9
        // 启动消费者线程
10
        new Thread(() -> {
11
            while (running) {
12
                try {
13
                    PublishTask task = queue.take(); // 阻塞获取
14
                    processTask(task);
15
                } catch (InterruptedException e) {
16
                    Thread.currentThread().interrupt();
17
                    break;
18
                }
19
            }
20
        }, "publish-consumer").start();
21
    }
22

23
    public void submit(PublishTask task) {
24
        boolean offered = queue.offer(task);
25
        if (!offered) {
26
            throw new BusinessException("发布队列已满，请稍后重试");
27
        }
28
        log.info("发布任务已加入队列: type={}, targetId={}",
29
                 task.getType(), task.getTargetId());
30
    }
31

32
    private void processTask(PublishTask task) {
33
        log.info("开始处理发布任务: type={}", task.getType());
34
        switch (task.getType()) {
35
            case FULL_PUBLISH:
36
                publishEngine.fullPublish(task.getSiteId());
37
                break;
38
            case CONTENT_PUBLISH:
39
                publishEngine.publishContent(
40
                    task.getSiteId(), task.getChannelId(), task.getContentId());
41
                break;
42
            case CHANNEL_PUBLISH:
43
                publishEngine.publishChannel(
44
                    task.getSiteId(), task.getChannelId());
45
                break;
46
        }
47
        log.info("发布任务完成: type={}", task.getType());
48
    }
49
}

展开收起

6.5 发布目录结构#

发布完成后，文件系统的目录结构：

1
/var/www/publish/
2
└── site_1/                        # 站点ID
3
    ├── index.html                 # 首页
4
    ├── about/
5
    │   └── index.html             # 关于我们（单页）
6
    ├── news/
7
    │   ├── index.html             # 新闻列表 第1页
8
    │   ├── index_2.html           # 新闻列表 第2页
9
    │   ├── index_3.html           # 新闻列表 第3页
10
    │   ├── 1001.html              # 新闻详情 ID=1001
11
    │   ├── 1002.html              # 新闻详情 ID=1002
12
    │   └── ...
13
    ├── products/
14
    │   ├── index.html
15
    │   ├── 2001.html
16
    │   └── ...
17
    ├── uploads/                   # 上传的文件
18
    │   ├── 2026/
19
    │   │   ├── 06/
20
    │   │   │   ├── abc123.jpg
21
    │   │   │   └── def456.pdf
22
    │   │   └── ...
23
    │   └── ...
24
    └── _resources/                # 全局资源
25
        ├── css/
26
        │   └── main.css
27
        ├── js/
28
        │   └── main.js
29
        └── images/
30
            └── logo.png

展开收起

6.6 发布后的 URL 访问链路#

以一个完整的访问为例，用户访问新闻详情页：

1
1. 用户浏览器输入: http://www.example.com/news/1001.html
2
       ↓
3
2. DNS 解析 → 服务器 IP
4
       ↓
5
3. Nginx 接收请求
6
       ↓
7
4. Nginx 检查: /var/www/publish/site_1/news/1001.html 是否存在
8
       ↓
9
5. 文件存在 → Nginx 直接返回静态文件（最高性能）
10
       ↓
11
6. 文件不存在 → Nginx 404
12
       ↓
13
7. (可选) Nginx 配置的 fallback → Tomcat 动态渲染
14
       location / {
15
           try_files $uri $uri/ @tomcat;
16
       }
17
       location @tomcat {
18
           proxy_pass http://127.0.0.1:8080;
19
       }

展开收起

七、模板配置与前端渲染#

7.1 模板配置流程#

在博达后台配置模板的完整流程：

1
1. 进入"模板管理"模块
2
       ↓
3
2. 上传 .ftl 模板文件（或在线编辑）
4
       ↓
5
3. 配置模板参数：
6
   - 模板名称
7
   - 模板类型（首页/列表/详情/搜索/404）
8
   - 关联站点
9
   - 预览图
10
   - 模板变量说明
11
       ↓
12
4. 进入"栏目管理"
13
       ↓
14
5. 选择栏目 → 编辑
15
       ↓
16
6. 在"列表模板"字段选择刚上传的模板
17
       ↓
18
7. 在"详情模板"字段选择刚上传的模板
19
       ↓
20
8. 保存栏目配置
21
       ↓
22
9. 全量发布站点
23
       ↓
24
10. 前台访问验证

展开收起

7.2 模板中调用资料库#

模板中通过自定义指令调用资料库中的数据。核心逻辑已在 2.3 节说明，这里给出一个更完整的前台列表页模板示例：

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>${channel.name} - ${site.name}</title>
7
    <meta name="keywords" content="${channel.keywords!site.keywords!}">
8
    <meta name="description" content="${channel.description!site.description!}">
9
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
10
</head>
11
<body>
12
    <!-- 页头 -->
13
    <#include "/_common/header.ftl">
14

15
    <!-- 面包屑 -->
16
    <div class="breadcrumb">
17
        <a href="${site.contextPath}/">首页</a>
18
        <#list breadcrumb as crumb>
19
            &gt; <a href="${crumb.url}">${crumb.name}</a>
20
        </#list>
21
    </div>
22

23
    <!-- 内容区域 -->
24
    <div class="container">
25
        <div class="main">
26
            <h1 class="page-title">${channel.name}</h1>
27

28
            <#if contentList?size gt 0>
29
                <ul class="news-list">
30
                    <#list contentList as item>
31
                        <li>
32
                            <#if item.isTop>
33
                                <span class="tag top">置顶</span>
34
                            </#if>
35
                            <#if item.isRecommend>
36
                                <span class="tag rec">推荐</span>
37
                            </#if>
38
                            <#if item.isBold>
39
                                <h3 class="bold">
40
                            <#else>
41
                                <h3>
42
                            </#if>
43
                                <a href="${item.url}">${item.title}</a>
44
                            </h3>
45
                            <p class="meta">
46
                                ${item.author!""}
47
                                <#if item.author?? && item.source??> | </#if>
48
                                ${item.source!""}
49
                                <span class="date">${item.publishDate?string("yyyy-MM-dd")}</span>
50
                            </p>
51
                            <p class="summary">${item.summary!""}</p>
52
                        </li>
53
                    </#list>
54
                </ul>
55

56
                <!-- 分页 -->
57
                <#if totalPages gt 1>
58
                    <div class="pagination">
59
                        <#if pageNo gt 1>
60
                            <a href="${channel.urlPrefix!channel.url}${pageNo - 1}.html">上一页</a>
61
                        </#if>
62
                        <#list 1..totalPages as p>
63
                            <a href="${channel.urlPrefix!channel.url}${p}.html"
64
                               class="${(p == pageNo)?string('active', '')}">${p}</a>
65
                        </#list>
66
                        <#if pageNo lt totalPages>
67
                            <a href="${channel.urlPrefix!channel.url}${pageNo + 1}.html">下一页</a>
68
                        </#if>
69
                    </div>
70
                </#if>
71
            <#else>
72
                <div class="empty">
73
                    <p>暂无内容</p>
74
                </div>
75
            </#if>
76
        </div>
77

78
        <!-- 侧边栏 -->
79
        <div class="sidebar">
80
            <#include "/_common/sidebar.ftl">
81
        </div>
82
    </div>
83

84
    <!-- 页脚 -->
85
    <#include "/_common/footer.ftl">
86

87
    <script src="${site.contextPath}/_resources/js/main.js"></script>
88
</body>
89
</html>

展开收起

7.3 详情页模板#

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>${content.title} - ${channel.name} - ${site.name}</title>
7
    <meta name="keywords" content="${content.keywords!channel.keywords!site.keywords!}">
8
    <meta name="description" content="${content.summary!channel.description!site.description!}">
9
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
10
</head>
11
<body>
12
    <#include "/_common/header.ftl">
13

14
    <div class="breadcrumb">
15
        <a href="${site.contextPath}/">首页</a>
16
        <#list breadcrumb as crumb>
17
            &gt; <a href="${crumb.url}">${crumb.name}</a>
18
        </#list>
19
        &gt; <span class="current">正文</span>
20
    </div>
21

22
    <div class="container">
23
        <div class="main detail">
24
            <h1 class="detail-title">${content.title}</h1>
25

26
            <#if content.subTitle?? && content.subTitle != "">
27
                <h2 class="detail-subtitle">${content.subTitle}</h2>
28
            </#if>
29

30
            <div class="detail-meta">
31
                <span>作者：${content.author!"佚名"}</span>
32
                <span>来源：${content.source!"本站"}</span>
33
                <span>发布时间：${content.publishDate?string("yyyy-MM-dd HH:mm")}</span>
34
                <span>浏览：<span id="viewCount">${content.viewCount!0}</span></span>
35
            </div>
36

37
            <div class="detail-content">
38
                ${content.content?no_esc}
39
            </div>
40

41
            <#if attachments?size gt 0>
42
                <div class="detail-attachments">
43
                    <h3>附件下载</h3>
44
                    <ul>
45
                        <#list attachments as file>
46
                            <li>
47
                                <a href="${file.filePath}" download="${file.fileName}">
48
                                    ${file.fileName}
49
                                    (${(file.fileSize / 1024)?string("0.00")}KB)
50
                                </a>
51
                                <span class="download-count">
52
                                    已下载 ${file.downloadCount} 次
53
                                </span>
54
                            </li>
55
                        </#list>
56
                    </ul>
57
                </div>
58
            </#if>
59

60
            <!-- 上下篇导航 -->
61
            <div class="detail-nav">
62
                <div class="prev">
63
                    <#if prevContent??>
64
                        上一篇：<a href="${prevContent.url}">${prevContent.title}</a>
65
                    <#else>
66
                        上一篇：没有了
67
                    </#if>
68
                </div>
69
                <div class="next">
70
                    <#if nextContent??>
71
                        下一篇：<a href="${nextContent.url}">${nextContent.title}</a>
72
                    <#else>
73
                        下一篇：没有了
74
                    </#if>
75
                </div>
76
            </div>
77
        </div>
78

79
        <div class="sidebar">
80
            <#include "/_common/sidebar.ftl">
81
        </div>
82
    </div>
83

84
    <#include "/_common/footer.ftl">
85
    <script src="${site.contextPath}/_resources/js/main.js"></script>
86
</body>
87
</html>

展开收起

7.4 多站点与模板继承#

博达支持多站点共享模板，也支持模板继承。模板继承的实现思路：

1
基础模板（base.ftl）
2
  └── 站点A首页（index_A.ftl，继承 base.ftl）
3
  └── 站点B首页（index_B.ftl，继承 base.ftl）

FreeMarker 本身不支持模板继承（像 Jinja2 的 extends），博达通过两种方式实现：

方式一：宏导入（推荐）

1
<#-- _common/base.ftl -->
2
<#macro pageLayout title keywords="" description="">
3
<!DOCTYPE html>
4
<html>
5
<head>
6
    <meta charset="UTF-8">
7
    <title>${title} - ${site.name}</title>
8
    <meta name="keywords" content="${keywords}">
9
    <meta name="description" content="${description}">
10
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
11
</head>
12
<body>
13
    <#include "/_common/header.ftl">
14
    <div class="container">
15
        <#nested>  <#-- 子模板内容插入点 -->
16
    </div>
17
    <#include "/_common/footer.ftl">
18
</body>
19
</html>
20
</#macro>
21

22
<#-- index/index.ftl 使用宏 -->
23
<#import "/_common/base.ftl" as base>
24
<@base.pageLayout title="首页" keywords="网站关键词">
25
    <h1>欢迎访问${site.name}</h1>
26
    <!-- 首页特有内容 -->
27
</@base.pageLayout>

展开收起

方式二：页面片段包含

1
<#-- 每个页面的框架都一样，只是中间内容不同 -->
2
<#include "/_common/html_head.ftl">
3
<#include "/_common/header.ftl">
4
<#include "/_common/nav.ftl">
5

6
<div class="container">
7
    <!-- 各页面自己的内容 -->
8
    <#nested>  <#-- 这里在实际模板中替换为具体内容 -->
9
</div>
10

11
<#include "/_common/footer.ftl">
12
<#include "/_common/html_foot.ftl">

八、二次开发与扩展#

8.1 自定义标签开发#

如果你需要博达模板中获取自定义数据源的指令，可以实现自己的 TemplateDirectiveModel：

1
@Component
2
public class CustomDataDirective implements TemplateDirectiveModel {
3

4
    @Override
5
    public void execute(Environment env, Map params, TemplateModel[] loopVars,
6
                        TemplateDirectiveBody body)
7
            throws TemplateException, IOException {
8

9
        // 1. 解析参数
10
        String type = getRequiredStringParam(params, "type");
11
        Integer limit = getIntParam(params, "limit", 10);
12

13
        // 2. 调用你的业务逻辑
14
        List<Map<String, Object>> dataList = yourBusinessService.getData(type, limit);
15

16
        // 3. 注入模板上下文
17
        DefaultObjectWrapper wrapper = new DefaultObjectWrapperBuilder(
18
            Configuration.VERSION_2_3_32).build();
19
        env.setVariable("dataList", wrapper.wrap(dataList));
20

21
        // 4. 渲染标签体
22
        if (body != null) {
23
            body.render(env.getOut());
24
        }
25
    }
26
}

展开收起

在 FreeMarker 配置中注册：

1
@Configuration
2
public class FreemarkerConfig {
3

4
    @Autowired
5
    private CustomDataDirective customDataDirective;
6

7
    @PostConstruct
8
    public void configureFreemarker() {
9
        Configuration cfg = FreeMarkerConfigurer.getConfiguration();
10
        cfg.setSharedVariable("custom", customDataDirective);
11
    }
12
}

然后在模板中就可以用了：

1
<@custom type="notice" limit="5">
2
    <#list dataList as item>
3
        <li><a href="${item.url}">${item.title}</a></li>
4
    </#list>
5
</@custom>

8.2 自定义发布监听器#

在发布流程中插入自定义逻辑（如：发布后推送通知、生成 PDF、刷新 CDN 缓存等）：

1
@Component
2
public class CustomPublishListener implements ApplicationListener<PublishEvent> {
3

4
    @Override
5
    public void onApplicationEvent(PublishEvent event) {
6
        PublishType type = event.getType();
7
        Integer siteId = event.getSiteId();
8
        Integer contentId = event.getContentId();
9

10
        switch (type) {
11
            case CONTENT_PUBLISHED:
12
                // 内容发布后：生成 PDF 版本
13
                generatePdf(contentId);
14
                // 刷新 CDN 缓存
15
                refreshCdnCache("/content/" + contentId + ".html");
16
                break;
17
            case FULL_PUBLISH_COMPLETED:
18
                // 全量发布完成后：通知管理员
19
                notifyAdmin("全量发布完成");
20
                break;
21
        }
22
    }
23
}

展开收起

8.3 集成 SSO 登录#

博达通常通过 Filter 或 Spring Security 集成学校现有的统一身份认证系统：

1
public class SsoAuthenticationFilter extends GenericFilterBean {
2

3
    @Override
4
    public void doFilter(ServletRequest request, ServletResponse response,
5
                         FilterChain chain) throws IOException, ServletException {
6
        HttpServletRequest httpRequest = (HttpServletRequest) request;
7
        HttpSession session = httpRequest.getSession(false);
8

9
        // 1. 检查 session 中是否有用户信息
10
        User user = (session != null)
11
            ? (User) session.getAttribute("_user")
12
            : null;
13

14
        if (user == null) {
15
            // 2. 检查 SSO Token（从请求头或 Cookie 中）
16
            String ssoToken = extractSsoToken(httpRequest);
17

18
            if (ssoToken != null) {
19
                // 3. 调用 SSO 接口验证 Token
20
                SsoResponse ssoResponse = ssoClient.validate(ssoToken);
21
                if (ssoResponse.isValid()) {
22
                    // 4. 查找或创建本地用户
23
                    user = userService.findOrCreate(ssoResponse.getUserId(),
24
                        ssoResponse.getUsername());
25
                    // 5. 写入 Session
26
                    if (session == null) {
27
                        session = httpRequest.getSession(true);
28
                    }
29
                    session.setAttribute("_user", user);
30
                }
31
            }
32
        }
33

34
        // 6. 将用户信息绑定到请求上下文
35
        if (user != null) {
36
            UserContextHolder.setUser(user);
37
        }
38

39
        try {
40
            chain.doFilter(request, response);
41
        } finally {
42
            UserContextHolder.clear();
43
        }
44
    }
45
}

展开收起

8.4 自定义内容导入导出#

博达通常支持通过 Excel 批量导入资料，也支持导出。以下是导出 Excel 的核心逻辑：

1
public void exportContents(Integer siteId, Integer channelId, OutputStream os) {
2
    List<Content> contents = contentService.getContentsByChannel(siteId, channelId);
3

4
    // 使用 Apache POI 生成 Excel
5
    try (XSSFWorkbook workbook = new XSSFWorkbook()) {
6
        XSSFSheet sheet = workbook.createSheet("资料导出");
7

8
        // 表头
9
        String[] headers = {"ID", "标题", "作者", "发布时间", "状态", "浏览次数"};
10
        Row headerRow = sheet.createRow(0);
11
        for (int i = 0; i < headers.length; i++) {
12
            Cell cell = headerRow.createCell(i);
13
            cell.setCellValue(headers[i]);
14
        }
15

16
        // 数据行
17
        int rowIdx = 1;
18
        for (Content content : contents) {
19
            Row row = sheet.createRow(rowIdx++);
20
            row.createCell(0).setCellValue(content.getId());
21
            row.createCell(1).setCellValue(content.getTitle());
22
            row.createCell(2).setCellValue(content.getAuthor());
23
            row.createCell(3).setCellValue(
24
                content.getPublishDate() != null
25
                    ? content.getPublishDate().toString() : "");
26
            row.createCell(4).setCellValue(content.getStatus());
27
            row.createCell(5).setCellValue(content.getViewCount());
28
        }
29

30
        workbook.write(os);
31
    } catch (IOException e) {
32
        throw new BusinessException("导出失败", e);
33
    }
34
}

展开收起

九、常见问题与优化#

9.1 性能优化#

问题	原因	优化方案
全量发布慢	渲染大量页面，单线程处理	使用线程池并发发布
前台访问慢	动态渲染未缓存	Nginx 缓存 + 静态页面优先
栏目树加载慢	递归查询数据库	一次加载全量数据，内存中建树
模板修改不生效	FreeMarker 缓存	`setTemplateUpdateDelay` 调小或重启
大附件上传超时	Tomcat 默认限制	修改 server.xml maxPostSize / maxSwallowSize
搜索慢	LIKE 全表扫描	使用全文索引或 Elasticsearch
Session 丢失	Tomcat 重启	使用 Redis 托管 Session

9.2 Nginx 配置优化#

1
server {
2
    listen 80;
3
    server_name www.example.com;
4
    return 301 https://$server_name$request_uri;
5
}
6

7
server {
8
    listen 443 ssl http2;
9
    server_name www.example.com;
10

11
    ssl_certificate     /etc/nginx/ssl/example.com.pem;
12
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
13

14
    # 发布目录根路径
15
    root /var/www/publish/site_1;
16

17
    # 静态资源缓存
18
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
19
        expires 30d;
20
        add_header Cache-Control "public, immutable";
21
        access_log off;
22
    }
23

24
    # HTML 页面缓存（但不缓存管理后台）
25
    location ~* \.html$ {
26
        expires 5m;
27
        add_header Cache-Control "public, must-revalidate";
28
    }
29

30
    # 先尝试静态文件，不存在则转发到 Tomcat
31
    location / {
32
        try_files $uri $uri/ @tomcat;
33
    }
34

35
    # Tomcat 后端（用于动态渲染）
36
    location @tomcat {
37
        proxy_pass http://127.0.0.1:8080;
38
        proxy_set_header Host $host;
39
        proxy_set_header X-Real-IP $remote_addr;
40
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
41
        proxy_set_header X-Forwarded-Proto $scheme;
42

43
        # 超时配置
44
        proxy_connect_timeout 60s;
45
        proxy_read_timeout 60s;
46
        proxy_send_timeout 60s;
47
    }
48

49
    # 限制上传大小
50
    client_max_body_size 100M;
51

52
    # 访问日志
53
    access_log /var/log/nginx/example.com.access.log;
54
    error_log  /var/log/nginx/example.com.error.log;
55
}

展开收起

9.3 Tomcat 配置优化#

conf/server.xml展开收起

1
<Connector port="8080" protocol="HTTP/1.1"
2
           connectionTimeout="20000"
3
           redirectPort="8443"
4
           maxPostSize="104857600"
5
           maxSwallowSize="104857600"
6
           URIEncoding="UTF-8"
7
           compression="on"
8
           compressionMinSize="1024"
9
           compressableMimeType="text/html,text/xml,text/css,text/javascript,application/javascript"/>
10

11
<!-- conf/context.xml -->
12
<Context>
13
    <!-- 静态资源缓存 -->
14
    <Resources cachingAllowed="true" cacheMaxSize="102400" />
15
</Context>

展开收起

十、实操案例：改造”党建”栏目的页面样式#

这一节用一个具体场景串联全文的知识点：学校官网的”党建”栏目页面太旧了，需要重新设计列表页和内容详情页的样式，涉及模板修改、栏目配置、资料编辑、发布的完整链路。

10.1 问题描述#

1
现有状态：
2
- 党建栏目路径：/dangjian/
3
- 列表页模板：/channel/list.ftl（与其他栏目共用，无法单独定制）
4
- 详情页模板：/content/detail.ftl（与其他栏目共用）
5
- 页面风格：蓝白色调，与学校主站一致
6
- 问题：党建栏目需要红色主题，且要展示党徽、入党誓词等特殊元素
7

8
目标：
9
1. 党建栏目使用独立的红色主题列表页
10
2. 详情页顶部增加党徽和"党建专栏"标题栏
11
3. 保持其他栏目不受影响

10.2 操作步骤#

第一步：新建党建专用模板文件#

在博达后台找到「模板管理」模块，上传或新建两个 .ftl 文件。

列表页模板：/channel/list_dangjian.ftl

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>${channel.name} - ${site.name}</title>
7
    <meta name="keywords" content="${channel.keywords!site.keywords!}">
8
    <meta name="description" content="${channel.description!site.description!}">
9

10
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
11
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/theme-dangjian.css">
12
</head>
13
<body>
14
    <#include "/_common/header.ftl">
15

16
    <#-- 党建专属 Banner -->
17
    <div class="dj-banner">
18
        <div class="dj-banner-content">
19
            <img src="${site.contextPath}/_resources/images/danghui.png"
20
                 alt="党徽" class="dj-emblem">
21
            <h1 class="dj-title">${channel.name}</h1>
22
            <p class="dj-subtitle">${channel.description!"不忘初心 牢记使命"}</p>
23
        </div>
24
    </div>
25

26
    <div class="container">
27
        <div class="breadcrumb">
28
            <a href="${site.contextPath}/">首页</a>
29
            <#list breadcrumb as crumb>
30
                &gt; <a href="${crumb.url}">${crumb.name}</a>
31
            </#list>
32
        </div>
33

34
        <div class="dj-layout">
35
            <div class="dj-main">
36
                <h2 class="dj-section-title">党建工作动态</h2>
37

38
                <@cms.contentList siteId="${site.id}" channelId="${channel.id}"
39
                                  pageNo="${pageNo!1}" pageSize="${channel.pageSize!20}">
40
                    <#list contents as item>
41
                        <article class="dj-news-item">
42
                            <span class="dj-news-date">${item.publishDate?string("yyyy-MM-dd")}</span>
43
                            <#if item.isTop>
44
                                <span class="tag top">重要</span>
45
                            </#if>
46
                            <h3><a href="${item.url}">${item.title}</a></h3>
47
                            <p class="dj-news-summary">${item.summary!""}</p>
48
                        </article>
49
                    </#list>
50
                </@cms.contentList>
51

52
                <#if totalPages gt 1>
53
                    <div class="pagination">
54
                        <#if pageNo gt 1>
55
                            <a href="${channel.url}${pageNo - 1}.html">上一页</a>
56
                        </#if>
57
                        <#list 1..totalPages as p>
58
                            <a href="${channel.url}${p}.html"
59
                               class="${(p == pageNo)?string('current', '')}">${p}</a>
60
                        </#list>
61
                        <#if pageNo lt totalPages>
62
                            <a href="${channel.url}${pageNo + 1}.html">下一页</a>
63
                        </#if>
64
                    </div>
65
                </#if>
66
            </div>
67

68
            <aside class="dj-sidebar">
69
                <#include "/_common/sidebar.ftl">
70
            </aside>
71
        </div>
72
    </div>
73

74
    <#include "/_common/footer.ftl">
75
    <script src="${site.contextPath}/_resources/js/main.js"></script>
76
</body>
77
</html>

展开收起

详情页模板：/content/detail_dangjian.ftl

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>${content.title} - ${channel.name} - ${site.name}</title>
7
    <meta name="keywords" content="${content.keywords!channel.keywords!site.keywords!}">
8
    <meta name="description" content="${content.summary!channel.description!site.description!}">
9

10
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
11
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/theme-dangjian.css">
12
</head>
13
<body>
14
    <#include "/_common/header.ftl">
15

16
    <div class="container">
17
        <div class="breadcrumb">
18
            <a href="${site.contextPath}/">首页</a>
19
            <#list breadcrumb as crumb>
20
                &gt; <a href="${crumb.url}">${crumb.name}</a>
21
            </#list>
22
            &gt; <span>正文</span>
23
        </div>
24

25
        <div class="dj-detail">
26
            <#-- 党建文章头部 -->
27
            <div class="dj-detail-header">
28
                <img src="${site.contextPath}/_resources/images/danghui.png"
29
                     alt="党徽" class="dj-detail-emblem">
30
                <h1 class="dj-detail-title">${content.title}</h1>
31
                <div class="dj-detail-meta">
32
                    <span>作者：${content.author!"佚名"}</span>
33
                    <span>来源：${content.source!"本站"}</span>
34
                    <span>发布时间：${content.publishDate?string("yyyy-MM-dd HH:mm")}</span>
35
                </div>
36
            </div>
37

38
            <#-- 正文 -->
39
            <div class="dj-detail-body">
40
                ${content.content?no_esc}
41
            </div>
42

43
            <#-- 上下篇 -->
44
            <div class="detail-nav">
45
                <div class="prev">
46
                    <#if prevContent??>
47
                        上一篇：<a href="${prevContent.url}">${prevContent.title}</a>
48
                    <#else>
49
                        上一篇：没有了
50
                    </#if>
51
                </div>
52
                <div class="next">
53
                    <#if nextContent??>
54
                        下一篇：<a href="${nextContent.url}">${nextContent.title}</a>
55
                    <#else>
56
                        下一篇：没有了
57
                    </#if>
58
                </div>
59
            </div>
60
        </div>
61
    </div>
62

63
    <#include "/_common/footer.ftl">
64
    <script src="${site.contextPath}/_resources/js/main.js"></script>
65
</body>
66
</html>

展开收起

第二步：编写党建主题 CSS#

在 _resources/css/ 下新建 theme-dangjian.css：

1
/* 党建主题样式 */
2

3
/* 顶部 Banner */
4
.dj-banner {
5
    background: linear-gradient(135deg, #C8102E 0%, #8B0000 100%);
6
    padding: 50px 0;
7
    text-align: center;
8
    color: #fff;
9
}
10

11
.dj-banner-content {
12
    max-width: 1200px;
13
    margin: 0 auto;
14
    padding: 0 20px;
15
}
16

17
.dj-emblem {
18
    width: 60px;
19
    height: 60px;
20
    margin-bottom: 15px;
21
}
22

23
.dj-title {
24
    font-size: 2rem;
25
    margin: 0 0 10px;
26
    font-weight: bold;
27
}
28

29
.dj-subtitle {
30
    font-size: 1rem;
31
    opacity: 0.9;
32
    margin: 0;
33
}
34

35
/* 党建布局 */
36
.dj-layout {
37
    display: flex;
38
    gap: 30px;
39
    padding: 30px 0;
40
}
41

42
.dj-main {
43
    flex: 1;
44
    min-width: 0;
45
}
46

47
.dj-sidebar {
48
    width: 300px;
49
    flex-shrink: 0;
50
}
51

52
/* 党建区块标题 */
53
.dj-section-title {
54
    font-size: 1.4rem;
55
    color: #C8102E;
56
    border-left: 4px solid #C8102E;
57
    padding-left: 12px;
58
    margin-bottom: 20px;
59
}
60

61
/* 党建新闻列表 */
62
.dj-news-item {
63
    padding: 18px 0;
64
    border-bottom: 1px solid #eee;
65
    display: flex;
66
    flex-wrap: wrap;
67
    align-items: baseline;
68
}
69

70
.dj-news-item:hover {
71
    background: #FFF5F5;
72
    margin: 0 -12px;
73
    padding-left: 12px;
74
    padding-right: 12px;
75
    border-radius: 4px;
76
}
77

78
.dj-news-date {
79
    color: #999;
80
    font-size: 0.85rem;
81
    margin-right: 15px;
82
    white-space: nowrap;
83
}
84

85
.dj-news-item h3 {
86
    flex: 1;
87
    min-width: 0;
88
    font-size: 1rem;
89
    margin: 0;
90
}
91

92
.dj-news-item h3 a {
93
    color: #333;
94
    text-decoration: none;
95
}
96

97
.dj-news-item h3 a:hover {
98
    color: #C8102E;
99
}
100

101
.dj-news-summary {
102
    width: 100%;
103
    color: #666;
104
    font-size: 0.9rem;
105
    margin: 8px 0 0;
106
}
107

108
/* 党建详情页 */
109
.dj-detail {
110
    padding: 30px 0;
111
}
112

113
.dj-detail-header {
114
    text-align: center;
115
    padding: 30px 0;
116
    border-bottom: 2px solid #C8102E;
117
    margin-bottom: 30px;
118
}
119

120
.dj-detail-emblem {
121
    width: 50px;
122
    height: 50px;
123
    margin-bottom: 15px;
124
}
125

126
.dj-detail-title {
127
    font-size: 1.8rem;
128
    color: #222;
129
    margin: 0 0 15px;
130
}
131

132
.dj-detail-meta {
133
    color: #999;
134
    font-size: 0.9rem;
135
}
136

137
.dj-detail-meta span {
138
    margin: 0 10px;
139
}
140

141
.dj-detail-body {
142
    line-height: 1.8;
143
    font-size: 1rem;
144
    color: #333;
145
}
146

147
.dj-detail-body p {
148
    margin: 0 0 1em;
149
}
150

151
/* 响应式 */
152
@media (max-width: 768px) {
153
    .dj-layout {
154
        flex-direction: column;
155
    }
156

157
    .dj-sidebar {
158
        width: 100%;
159
    }
160

161
    .dj-banner {
162
        padding: 30px 0;
163
    }
164

165
    .dj-title { font-size: 1.5rem; }
166

167
    .dj-detail-title { font-size: 1.3rem; }
168
}

展开收起

第三步：上传资源文件#

将党徽图片 danghui.png 上传到 _resources/images/ 目录。操作路径：

1
后台 → 资源管理 → 图片管理 → 上传文件 → 选择 danghui.png
2
    → 上传完成后确认文件路径为 /_resources/images/danghui.png

如果手头没有党徽图片，也可以使用字体图标或 Unicode 符号替代：

1
<#-- 替代方案：使用 Unicode 字符 ★ 或 CSS 绘制 -->
2
<div class="dj-emblem-placeholder">★</div>

第四步：修改栏目配置，指定独立模板#

进入「栏目管理」，找到党建栏目：

1
后台 → 栏目管理 → 找到"党建"栏目 → 点击"编辑"
2
    → "列表页模板" → 选择 /channel/list_dangjian.ftl
3
    → "详情页模板" → 选择 /content/detail_dangjian.ftl
4
    → "模板风格" → 输入 dangjian（用于 CSS/JS 动态加载）
5
    → 保存

关键点：这一步只改了党建栏目的模板指向，其他栏目仍然使用原来的 /channel/list.ftl 和 /content/detail.ftl，完全不受影响。

第五步：编辑或新建党建内容#

1
后台 → 内容管理 → 选择党建栏目 → 点击"新增"
2
    → 填写标题、作者、正文等内容
3
    → 如有需要，设置"置顶"或"推荐"
4
    → 点击"保存"（状态为草稿）
5
    → 如需要审核流程 → "提交审核"
6
    → 审核通过后 → "发布"

也可以批量导入已有内容：

1
后台 → 内容管理 → 党建栏目 → 导入 → 选择 Excel 文件
2
    → 字段映射：Excel 列 → 系统字段
3
    → 预览确认 → 执行导入

第六步：发布#

内容发布后，需要触发发布引擎重新生成静态页面：

方案一：发布单条内容（增量发布）

1
后台 → 内容管理 → 党建栏目 → 勾选需要发布的内容
2
    → 点击"发布"按钮
3
    → 系统自动：生成详情页 → 重新生成列表页 → 如设了推荐则重新生成首页

方案二：发布整个栏目（推荐首次使用）

1
后台 → 栏目管理 → 党建栏目 → 点击"发布"
2
    → 选择发布范围：当前栏目（含子栏目）
3
    → 点击"确定"
4
    → 发布队列显示进度 → 完成后可访问前台查看

方案三：全量发布站点

1
后台 → 站点管理 → 点击"全量发布"
2
    → 确认 → 系统重新生成所有页面
3
    → 耗时取决于站点大小（一般 1-10 分钟）

第七步：前台验证#

发布完成后，在浏览器中访问：

1
列表页：http://www.example.com/dangjian/
2
详情页：http://www.example.com/dangjian/1001.html

验证清单：

1
[✅] 列表页显示红色主题 Banner
2
[✅] 党徽图片正常显示
3
[✅] 新闻列表展示正常
4
[✅] 分页功能正常
5
[✅] 点击标题进入详情页
6
[✅] 详情页顶部有党徽和党建标题栏
7
[✅] 正文排版正确
8
[✅] 上下篇导航正常
9
[✅] 移动端布局自适应
10
[✅] 其他栏目未受影响（如 /news/ 仍是蓝白风格）

10.3 如果改完没生效怎么办？#

这是博达开发中最常见的问题。按照优先级排查：

1
问题：前台看不到修改效果
2
    │
3
    ├── 是否发布了？
4
    │    静态页面没重新生成，旧文件还在 → 重新发布
5
    │
6
    ├── 浏览器缓存？
7
    │    Ctrl+F5 强制刷新，或打开无痕模式访问
8
    │
9
    ├── 模板路径配置对了？
10
    │    回后台检查栏目的"列表页模板"和"详情页模板"字段
11
    │
12
    ├── 模板文件上传位置正确？
13
    │    确认 .ftl 文件在正确的站点模板目录下
14
    │
15
    ├── CSS/JS 路径正确？
16
    │    浏览器 F12 → Network 看 CSS 是否 200
17
    │    检查 `${site.contextPath}` 是否正常解析
18
    │
19
    └── 发布目录权限？
20
        检查 Tomcat 对发布目录是否有写入权限

展开收起

10.4 扩展场景#

掌握了党建栏目的改造方法，以下场景也是同样的操作流程：

场景	改模板	改 CSS	建栏目	加内容	发布
新增一个”主题教育”栏目	可用党建模板改	复用或新建	✅	✅	✅
改造”通知公告”列表样式	✅	✅	不改	不改	✅
首页加一个党建动态区块	改 `index.ftl`	改 `main.css`	不改	不改	✅
给所有详情页加分享按钮	改 `detail.ftl`	改 `main.css`	不改	不改	✅
新建一个独立专题站点	✅	✅	✅	✅	✅

所有操作的底层逻辑都围绕同一个流程：

1
修改模板/样式 → 配置栏目 → 编辑内容 → 发布 → 验证

理解这个链路，就能在博达平台上独立完成任何前端改造需求。

十一、总结#

博达网站群管理平台的核心设计哲学可以概括为三句话：

内容与展现分离：资料库只存数据，模板只负责渲染，通过 FreeMarker 引擎在发布时合并
静态优先：发布引擎生成纯静态 HTML，Nginx 直接服务于用户，Tomcat 只做管理后台和动态渲染
站点群统一管理：一套后台管理多站点，站点间栏目、模板、资料隔离，通过域名解析分发

理解这套机制后，大部分开发场景都能应对：

改样式 → 编辑 .ftl 模板文件，修改 HTML 结构和 CSS
加功能 → 开发自定义 FreeMarker 指令，在模板中调用
改流程 → 修改 Java Service 层或发布引擎
做集成 → 通过 Filter、Listener、API 对接外部系统

博达的架构虽然年代较早（基于 Servlet + JSP + FreeMarker），但”静态化发布”这个设计理念在今天来看仍然是正确的——静态页面的性能和安全性是动态页面无法比拟的。理解它的内部逻辑，不只是为了维护一个 CMS，更是为了理解”内容管理”这个领域最基本的问题：如何高效地把数据变成用户可以访问的页面。

前端基础回顾：HTML、CSS、JS 到底学到什么程度才够

Wed, 06 May 2026 00:00:00 GMT

概述#

前端技术日新月异，但 HTML、CSS、JavaScript 这三个基础始终不变。框架会过时，构建工具会迭代，但 DOM 操作、布局原理、事件机制这些东西，十年后仍然有用。

这篇文章不教你怎么用 React 或 Vue，而是回到基础——浏览器到底怎么理解你的代码。

一、HTML — 语义与结构#

1.1 HTML 不是”写标签”#

很多人觉得 HTML 就是把内容用标签包起来。这种理解太浅了。HTML 的核心是语义——用正确的标签表达内容的含义，而不是它的样式。

1
<!-- 错误：用 div 模拟标题 -->
2
<div class="heading">欢迎来到我的网站</div>
3
<div class="subtitle">这是一个个人博客</div>
4

5
<!-- 正确：使用语义标签 -->
6
<h1>欢迎来到我的网站</h1>
7
<p>这是一个个人博客</p>

浏览器、搜索引擎、屏幕阅读器都依赖 HTML 的语义来理解页面。<h1> 不只让文字变大变粗，它告诉浏览器”这是本页最重要的标题”。搜索引擎会给它更高的权重，屏幕阅读器会单独朗读。

1.2 文档结构#

1
<!DOCTYPE html>
2
<html lang="zh-CN">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>页面标题</title>
7
    <meta name="description" content="页面描述，SEO 用">
8
    <link rel="stylesheet" href="style.css">
9
</head>
10
<body>
11
    <header>
12
        <nav>
13
            <ul>
14
                <li><a href="/">首页</a></li>
15
                <li><a href="/about">关于</a></li>
16
            </ul>
17
        </nav>
18
    </header>
19
    <main>
20
        <article>
21
            <h1>文章标题</h1>
22
            <section>
23
                <h2>章节标题</h2>
24
                <p>内容...</p>
25
            </section>
26
        </article>
27
        <aside>
28
            <h2>侧边栏</h2>
29
        </aside>
30
    </main>
31
    <footer>
32
        <p>&copy; 2026</p>
33
    </footer>
34
</body>
35
</html>

展开收起

HTML5 引入了语义化标签（<header>、<nav>、<main>、<article>、<section>、<aside>、<footer>），这些标签和 <div> 在渲染上没有区别，但它们表达了结构。

1.3 常用标签速查#

标签	用途	注意
`<h1>`~`<h6>`	标题	一级标题每页只有一个
`<p>`	段落	不要用 `<br>` 换段落
`<a>`	链接	`href` 必填，`target="_blank"` 加 `rel="noopener"`
`<img>`	图片	`alt` 属性必填（无障碍）
`<ul>` / `<ol>`	无序/有序列表	`<li>` 是直接子元素
`<table>`	表格	只用表格数据，不要用来布局
`<form>`	表单	`action` + `method`
`<input>`	输入框	`type` 很重要（text/email/number/password/date/checkbox/radio）
`<button>`	按钮	比 `<div>` 做按钮更好（可访问性）
`<div>`	无语义容器	最后一个选择，先用语义标签
`<span>`	行内容器	包裹文本片段

1.4 表单与输入#

表单是 Web 交互的基础。理解表单的提交方式是关键：

1
<!-- GET 提交：参数在 URL 上，用于搜索 -->
2
<form action="/search" method="GET">
3
    <label for="q">搜索：</label>
4
    <input type="text" id="q" name="q" required>
5
    <button type="submit">搜索</button>
6
</form>
7

8
<!-- POST 提交：参数在请求体中，用于提交数据 -->
9
<form action="/api/register" method="POST">
10
    <label for="email">邮箱：</label>
11
    <input type="email" id="email" name="email" required>
12

13
    <label for="password">密码：</label>
14
    <input type="password" id="password" name="password" minlength="6" required>
15

16
    <label>
17
        <input type="checkbox" name="agree" required>
18
        同意用户协议
19
    </label>
20

21
    <button type="submit">注册</button>
22
</form>

展开收起

<label> 的 for 属性关联到 <input> 的 id，点击标签时自动聚焦输入框。这不仅提升可用性，也是无障碍的基本要求。

二、CSS — 布局与样式#

2.1 CSS 的本质#

CSS 是”选择元素 → 设置属性”的声明式语言。它告诉浏览器页面应该长什么样，而不是怎么画出这个样。

1
/* 选择器 { 属性: 值; } */
2
h1 {
3
    color: #333;
4
    font-size: 2rem;
5
    margin-bottom: 1em;
6
}

2.2 选择器#

CSS 选择器决定了样式应用在哪些元素上。掌握选择器是写好 CSS 的第一步。

1
/* 基本选择器 */
2
*              /* 通配符，选中所有元素 */
3
div            /* 标签选择器 */
4
.class-name    /* 类选择器 */
5
#id-name       /* ID 选择器（慎用，优先级太高） */
6

7
/* 组合选择器 */
8
div p          /* 后代选择器（div 里面的所有 p） */
9
div > p        /* 子代选择器（div 的直接子 p） */
10
h1 + p         /* 相邻兄弟选择器（h1 后面紧挨着的 p） */
11
h1 ~ p         /* 通用兄弟选择器（h1 后面的所有 p） */
12

13
/* 属性选择器 */
14
[type="text"]           /* type 等于 text */
15
[href^="https"]         /* href 以 https 开头 */
16
[src$=".jpg"]           /* src 以 .jpg 结尾 */
17
[class*="btn"]          /* class 包含 btn */
18

19
/* 伪类（元素的状态） */
20
a:hover                 /* 鼠标悬停 */
21
a:active                /* 鼠标按下 */
22
a:visited               /* 已访问 */
23
input:focus             /* 聚焦 */
24
li:first-child          /* 第一个子元素 */
25
li:last-child           /* 最后一个子元素 */
26
li:nth-child(odd)       /* 奇数行 */
27
li:nth-child(3n+1)      /* 每 3 个的第一个 */
28
:not(.disabled)         /* 排除 */
29

30
/* 伪元素（元素的特定部分） */
31
::before                /* 元素前插入内容 */
32
::after                 /* 元素后插入内容 */
33
::first-line            /* 第一行 */
34
::selection             /* 选中部分 */

展开收起

2.3 盒模型——CSS 最核心的概念#

每一个 HTML 元素都是一个矩形盒子。盒模型决定了这个盒子在页面中占多大空间。

1
┌──────────────────────────────────┐
2
│         margin（外边距）           │
3
│  ┌────────────────────────────┐  │
4
│  │      border（边框）          │  │
5
│  │  ┌──────────────────────┐  │  │
6
│  │  │    padding（内边距）    │  │  │
7
│  │  │  ┌────────────────┐  │  │  │
8
│  │  │  │    content      │  │  │  │
9
│  │  │  │  （内容区域）     │  │  │  │
10
│  │  │  └────────────────┘  │  │  │
11
│  │  └──────────────────────┘  │  │
12
│  └────────────────────────────┘  │
13
└──────────────────────────────────┘

1
/* box-sizing 决定了宽度的计算方式 */
2
box-sizing: content-box;  /* 默认：width = content 宽度 */
3
box-sizing: border-box;   /* 推荐：width = content + padding + border */
4

5
/* 一个好实践：全局设置 border-box */
6
*, *::before, *::after {
7
    box-sizing: border-box;
8
}

content-box 和 border-box 的区别：

1
/* content-box（默认） */
2
/* width: 200px → 内容区 200px */
3
/* 实际占用宽度 = 200 + 10*2 + 2*2 = 224px */
4
.box {
5
    width: 200px;
6
    padding: 10px;
7
    border: 2px solid black;
8
}
9

10
/* border-box（推荐） */
11
/* width: 200px → 总宽度 = 200px */
12
/* 内容区宽度 = 200 - 10*2 - 2*2 = 176px */
13
.box {
14
    box-sizing: border-box;
15
    width: 200px;
16
    padding: 10px;
17
    border: 2px solid black;
18
}

展开收起

2.4 布局方案演变#

CSS 的布局能力经历了三个阶段：

1
传统：display: block / inline / table
2
经典：float + clear + position
3
现代：Flexbox + Grid

Flexbox（一维布局）#

Flexbox 解决的是”在一行或一列中排列元素”的问题。它是最常用、最好用的布局方案。

1
/* 容器设置 */
2
.container {
3
    display: flex;          /* 开启 flex 布局 */
4
    flex-direction: row;    /* 主轴方向：row | column */
5
    justify-content: center; /* 主轴对齐方式 */
6
    align-items: center;     /* 交叉轴对齐方式 */
7
    flex-wrap: wrap;        /* 是否换行 */
8
    gap: 16px;             /* 项目间距（现代写法） */
9
}
10

11
/* 项目设置 */
12
.item {
13
    flex: 1;               /* 等分剩余空间 */
14
    flex: 0 0 auto;        /* flex-grow flex-shrink flex-basis */
15
    align-self: center;    /* 单独对齐方式 */
16
    order: -1;             /* 改变顺序 */
17
}

展开收起

常用 flex 布局模式：

1
/* 水平垂直居中 */
2
.center {
3
    display: flex;
4
    justify-content: center;
5
    align-items: center;
6
    min-height: 100vh;  /* 相对于视口高度 */
7
}
8

9
/* 等分布局 */
10
.equal-cols {
11
    display: flex;
12
    gap: 20px;
13
}
14
.equal-cols > * {
15
    flex: 1;
16
}
17

18
/* 两端对齐导航 */
19
.nav {
20
    display: flex;
21
    justify-content: space-between;
22
    align-items: center;
23
}
24

25
/* 右侧固定，左侧自适应 */
26
.layout {
27
    display: flex;
28
}
29
.sidebar {
30
    width: 240px;
31
    flex-shrink: 0;
32
}
33
.main {
34
    flex: 1;
35
}

展开收起

Grid（二维布局）#

Grid 是 CSS 最强布局方案，适合做页面整体框架和复杂网格。

1
.container {
2
    display: grid;
3
    grid-template-columns: 1fr 2fr 1fr;  /* 三列，比例 1:2:1 */
4
    grid-template-rows: auto 1fr auto;     /* 三行 */
5
    gap: 20px;
6
    /* 简写 */
7
    grid-template:
8
        "header header header" auto
9
        "sidebar main aside" 1fr
10
        "footer footer footer" auto
11
        / 1fr 2fr 1fr;
12
}
13
.header { grid-area: header; }
14
.sidebar { grid-area: sidebar; }
15
.main { grid-area: main; }
16
.aside { grid-area: aside; }
17
.footer { grid-area: footer; }
18

19
/* 自动填充网格 */
20
.gallery {
21
    display: grid;
22
    grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
23
    gap: 16px;
24
}

展开收起

2.5 定位#

1
/* 静态定位（默认） */
2
position: static;
3

4
/* 相对定位：相对于自身原本位置偏移 */
5
position: relative;
6
top: 10px;
7
left: 10px;
8

9
/* 绝对定位：相对于最近的 position:relative/absolute/fixed 的父元素 */
10
position: absolute;
11
top: 0;
12
right: 0;
13

14
/* 固定定位：相对于视口 */
15
position: fixed;
16
bottom: 20px;
17
right: 20px;
18

19
/* 粘性定位：滚动到某个位置后固定 */
20
position: sticky;
21
top: 0;  /* 到顶部时固定 */

展开收起

2.6 响应式设计#

1
/* 媒体查询 */
2
/* 手机：< 768px */
3
/* 平板：768px ~ 1024px */
4
/* 桌面：> 1024px */
5

6
/* 移动优先：先写手机样式，再覆盖更大的屏幕 */
7
.container {
8
    padding: 16px;
9
    max-width: 100%;
10
}
11

12
@media (min-width: 768px) {
13
    .container {
14
        padding: 24px;
15
        max-width: 720px;
16
        margin: 0 auto;
17
    }
18
}
19

20
@media (min-width: 1024px) {
21
    .container {
22
        max-width: 960px;
23
        padding: 32px;
24
    }
25
}
26

27
/* 响应式图片 */
28
img {
29
    max-width: 100%;
30
    height: auto;
31
}
32

33
/* 响应式字体 */
34
html {
35
    font-size: 16px;  /* 基准 */
36
}
37
h1 { font-size: 2rem; }  /* 32px */
38
p { font-size: 1rem; }   /* 16px */
39

40
@media (min-width: 768px) {
41
    html { font-size: 18px; }  /* 整体放大 */
42
}
43

44
/* 使用 clamp 实现流体字体 */
45
h1 {
46
    font-size: clamp(1.5rem, 4vw, 3rem);
47
}

展开收起

三、JavaScript — 行为与交互#

3.1 JavaScript 在浏览器中的角色#

HTML 负责结构，CSS 负责样式，JavaScript 负责行为。JS 在浏览器中的核心能力：

操作 DOM：增删改查 HTML 元素
处理事件：响应用户的点击、输入、滚动等操作
网络请求：通过 Fetch/XMLHttpRequest 与服务器通信
存储数据：cookie、localStorage、sessionStorage
操作画布：Canvas、WebGL 绘图
处理异步：Promise、async/await

3.2 变量与类型#

1
// 声明变量
2
var old = '不要用 var'       // 函数作用域，有提升（hoisting）
3
let name = 'ES6 写法'        // 块级作用域，推荐
4
const PI = 3.14159          // 常量，引用类型不可重新赋值
5

6
// 值类型
7
typeof 42                   // 'number'
8
typeof 'hello'              // 'string'
9
typeof true                 // 'boolean'
10
typeof undefined            // 'undefined'
11
typeof null                 // 'object'（语言 bug，不要纠结）
12
typeof Symbol()             // 'symbol'
13
typeof 9007199254740991n    // 'bigint'
14

15
// 引用类型
16
typeof {}                   // 'object'
17
typeof []                   // 'object'（数组也是对象）
18
typeof function() {}        // 'function'

展开收起

类型转换是 JS 最常见的坑：

1
// 隐式转换（能避免就避免）
2
'5' - 3     // 2（字符串转数字）
3
'5' + 3     // '53'（数字转字符串，+ 有字符串优先）
4
'5' == 5    // true（== 会做类型转换）
5
'5' === 5   // false（=== 不做类型转换，推荐）
6

7
// 显式转换
8
Number('42')        // 42
9
String(42)          // '42'
10
Boolean(0)          // false
11
Boolean('')         // false
12
Boolean(null)       // false
13
Boolean(undefined)  // false
14
Boolean('false')    // true（非空字符串都是 true！）

3.3 函数#

1
// 函数声明（会被提升）
2
function add(a, b) {
3
    return a + b;
4
}
5

6
// 函数表达式（不会被提升）
7
const add = function(a, b) {
8
    return a + b;
9
};
10

11
// 箭头函数（ES6）
12
const add = (a, b) => a + b;
13
const square = x => x * x;
14
const noArgs = () => console.log('no params');
15

16
// 箭头函数的 this 指向外层作用域（重要！）
17
const obj = {
18
    name: 'obj',
19
    fn: function() {
20
        console.log(this.name);  // 'obj'，this 指向 obj
21
    },
22
    arrowFn: () => {
23
        console.log(this.name);  // undefined，this 指向外层（window/global）
24
    }
25
};
26

27
// 默认参数
28
function greet(name = '游客') {
29
    return `你好，${name}`;
30
}
31

32
// 剩余参数
33
function sum(...numbers) {
34
    return numbers.reduce((a, b) => a + b, 0);
35
}
36

37
// 解构参数
38
function createUser({ name, age = 18, email }) {
39
    return { name, age, email };
40
}
41
createUser({ name: '张三', email: 'z@example.com' });

展开收起

3.4 DOM 操作#

1
// 查询元素
2
document.getElementById('id')
3
document.querySelector('.class')       // 返回第一个匹配
4
document.querySelectorAll('div span')  // 返回 NodeList（可遍历）
5
document.getElementsByClassName('cls') // 返回 HTMLCollection（动态）
6
document.getElementsByTagName('div')
7

8
// 创建元素
9
const div = document.createElement('div');
10
div.textContent = 'Hello';
11
div.className = 'box';
12
div.id = 'myBox';
13
div.setAttribute('data-index', '1');
14

15
// 插入元素
16
parent.appendChild(div);
17
parent.insertBefore(div, referenceChild);
18
parent.prepend(div);     // 插到最前面
19
parent.append(div);      // 插到最后面
20
element.insertAdjacentHTML('beforeend', '<span>new</span>');
21

22
// 删除元素
23
element.remove();   // 直接删除（推荐）
24
parent.removeChild(element);
25

26
// 修改元素
27
element.textContent = '纯文本';          // 安全，不解析 HTML
28
element.innerHTML = '<b>富文本</b>';     // 有 XSS 风险
29
element.style.color = 'red';
30
element.style.display = 'flex';
31
element.classList.add('active');
32
element.classList.remove('hidden');
33
element.classList.toggle('expanded');
34
element.classList.contains('active');   // true/false
35

36
// 遍历 DOM
37
element.children           // 子元素（HTMLCollection）
38
element.childNodes         // 子节点（包含文本节点）
39
element.parentElement      // 父元素
40
element.nextElementSibling // 下一个兄弟元素
41
element.previousElementSibling // 上一个兄弟元素
42
element.closest('.wrapper') // 向上查找最近的匹配元素

展开收起

3.5 事件#

1
// 添加事件
2
button.addEventListener('click', function(event) {
3
    console.log('点击了', event.target);
4
});
5

6
// 移除事件（必须使用同一个函数引用）
7
function handler(e) { console.log(e); }
8
button.addEventListener('click', handler);
9
button.removeEventListener('click', handler);
10

11
// 事件对象
12
element.addEventListener('click', (e) => {
13
    e.target          // 触发事件的元素
14
    e.currentTarget   // 绑定事件的元素
15
    e.preventDefault()  // 阻止默认行为
16
    e.stopPropagation() // 阻止事件冒泡
17
});
18

19
// 事件委托：利用冒泡机制，在父元素上统一处理
20
document.querySelector('ul').addEventListener('click', (e) => {
21
    if (e.target.tagName === 'LI') {
22
        console.log('点击了 li', e.target.textContent);
23
    }
24
});
25

26
// 常用事件
27
click        // 点击
28
dblclick     // 双击
29
mouseenter   // 鼠标进入
30
mouseleave   // 鼠标离开
31
mousemove    // 鼠标移动
32
input        // 输入框内容变化
33
change       // 输入框失去焦点时值变化
34
submit       // 表单提交
35
keydown      // 键盘按下
36
keyup        // 键盘抬起
37
scroll       // 滚动
38
focus        // 聚焦
39
blur         // 失焦
40
load         // 页面/图片加载完成
41
DOMContentLoaded  // DOM 解析完成（不等图片加载）
42

43
// 自定义事件
44
const event = new CustomEvent('app:update', { detail: { id: 1 } });
45
window.dispatchEvent(event);
46

47
window.addEventListener('app:update', (e) => {
48
    console.log('收到更新:', e.detail);
49
});

展开收起

3.6 异步 JavaScript#

1
// 回调（Callback）—— 传统写法
2
function fetchData(callback) {
3
    setTimeout(() => {
4
        callback({ id: 1, name: 'data' });
5
    }, 1000);
6
}
7
fetchData((data) => {
8
    console.log(data);
9
});
10

11
// Promise —— 解决回调地狱
12
function fetchData() {
13
    return new Promise((resolve, reject) => {
14
        setTimeout(() => {
15
            resolve({ id: 1, name: 'data' });
16
            // reject(new Error('失败')); // 错误情况
17
        }, 1000);
18
    });
19
}
20

21
fetchData()
22
    .then(data => {
23
        console.log(data);
24
        return fetchData(); // 链式调用
25
    })
26
    .then(moreData => {
27
        console.log(moreData);
28
    })
29
    .catch(error => {
30
        console.error(error);
31
    })
32
    .finally(() => {
33
        console.log('无论如何都会执行');
34
    });
35

36
// async/await —— 最优雅的异步写法
37
async function getData() {
38
    try {
39
        const data = await fetchData();
40
        console.log(data);
41
        const moreData = await fetchData();
42
        console.log(moreData);
43
    } catch (error) {
44
        console.error(error);
45
    }
46
}
47

48
// 并发请求
49
async function getMultipleData() {
50
    const [users, posts, comments] = await Promise.all([
51
        fetch('/api/users'),
52
        fetch('/api/posts'),
53
        fetch('/api/comments')
54
    ]);
55
    return { users, posts, comments };
56
}

展开收起

3.7 网络请求#

1
// Fetch API（现代写法）
2
async function getUsers() {
3
    const response = await fetch('https://api.example.com/users');
4

5
    if (!response.ok) {
6
        throw new Error(`HTTP ${response.status}`);
7
    }
8

9
    const data = await response.json();
10
    return data;
11
}
12

13
// POST 请求
14
async function createUser(userData) {
15
    const response = await fetch('https://api.example.com/users', {
16
        method: 'POST',
17
        headers: {
18
            'Content-Type': 'application/json',
19
            'Authorization': `Bearer ${token}`
20
        },
21
        body: JSON.stringify(userData)
22
    });
23
    return response.json();
24
}
25

26
// 传统 XMLHttpRequest
27
function loadData(url, callback) {
28
    const xhr = new XMLHttpRequest();
29
    xhr.open('GET', url);
30
    xhr.onload = () => {
31
        if (xhr.status === 200) {
32
            callback(null, JSON.parse(xhr.responseText));
33
        } else {
34
            callback(new Error(`HTTP ${xhr.status}`));
35
        }
36
    };
37
    xhr.onerror = () => callback(new Error('网络错误'));
38
    xhr.send();
39
}

展开收起

3.8 数组方法#

数组操作是前端开发中最频繁的任务：

1
const arr = [1, 2, 3, 4, 5];
2

3
// 遍历
4
arr.forEach(item => console.log(item));
5

6
// 映射
7
const doubled = arr.map(x => x * 2);
8
// [2, 4, 6, 8, 10]
9

10
// 过滤
11
const evens = arr.filter(x => x % 2 === 0);
12
// [2, 4]
13

14
// 查找
15
const found = arr.find(x => x > 3);  // 4（第一个匹配）
16
const index = arr.findIndex(x => x > 3);  // 3
17

18
// 判断
19
const allPositive = arr.every(x => x > 0);  // true
20
const hasNegative = arr.some(x => x < 0);   // false
21

22
// 累计
23
const sum = arr.reduce((acc, cur) => acc + cur, 0);  // 15
24
const max = arr.reduce((a, b) => Math.max(a, b));    // 5
25

26
// 扁平化
27
const nested = [1, [2, 3], [4, [5, 6]]];
28
nested.flat();         // [1, 2, 3, 4, [5, 6]]
29
nested.flat(2);        // [1, 2, 3, 4, 5, 6]
30

31
// 排序（注意：默认按字符串排序）
32
arr.sort((a, b) => a - b);  // 升序
33
arr.sort((a, b) => b - a);  // 降序
34

35
// 去重
36
const unique = [...new Set([1, 2, 2, 3, 3, 4])];  // [1, 2, 3, 4]
37

38
// 不可变操作（重要！）
39
const added = [...arr, 6];        // 添加
40
const removed = arr.filter(x => x !== 3);  // 删除
41
const updated = arr.map(x => x === 3 ? 99 : x);  // 更新

展开收起

3.9 对象与原型#

1
// 对象字面量
2
const user = {
3
    name: '张三',
4
    age: 25,
5
    greet() {
6
        console.log(`你好，我是${this.name}`);
7
    }
8
};
9

10
// 属性简写
11
const name = '张三';
12
const user = { name };  // 等价于 { name: name }
13

14
// 计算属性名
15
const key = 'email';
16
const user = { [key]: 'z@example.com' };
17

18
// 可选链（ES2020）
19
const city = user?.address?.city ?? '未知';  // ?. 避免层层判断
20
// ?? 是空值合并运算符：只有当 left 是 null/undefined 时才用 right
21

22
// 对象解构
23
const { name, age, ...rest } = user;
24

25
// 展开
26
const clone = { ...user };
27
const merged = { ...obj1, ...obj2 };
28

29
// Object 静态方法
30
Object.keys(obj)      // 键数组
31
Object.values(obj)    // 值数组
32
Object.entries(obj)   // [键, 值] 数组
33
Object.assign(target, source)  // 合并（浅拷贝）

展开收起

3.10 模块#

math.js

1
// 导出（ES Module）
2
export const PI = 3.14159;
3
export function add(a, b) { return a + b; }
4
export default class Calculator { ... }
5

6
// 导入
7
import Calculator, { PI, add as sum } from './math.js';
8
import * as Math from './math.js';

四、三者的协作#

4.1 浏览器渲染流程#

当浏览器加载一个页面时，它的工作流程：

1
HTML 解析 → DOM 树
2
CSS 解析 → CSSOM 树
3
        ↓
4
DOM + CSSOM → Render Tree
5
        ↓
6
Layout（布局计算）
7
        ↓
8
Paint（绘制像素）
9
        ↓
10
Composite（合成图层）

JavaScript 在这中间扮演的角色：

解析 HTML 时遇到 <script> 标签会阻塞解析（默认行为）
defer 属性让 JS 在 HTML 解析完成后执行（顺序执行）
async 属性让 JS 下载完立即执行（不保证顺序）

1
<script src="script.js"></script>
2
<!-- 阻塞 HTML 解析，下载并执行完才继续解析 -->
3

4
<script defer src="script.js"></script>
5
<!-- 与 HTML 解析并行下载，解析完成后按顺序执行 -->
6

7
<script async src="script.js"></script>
8
<!-- 与 HTML 解析并行下载，下载完立即执行 -->

4.2 DOMContentLoaded vs Load#

1
// DOM 树构建完成（图片可能还没加载）
2
document.addEventListener('DOMContentLoaded', () => {
3
    console.log('DOM 就绪');
4
});
5

6
// 所有资源（图片、样式、字体）加载完成
7
window.addEventListener('load', () => {
8
    console.log('全加载完成');
9
});

4.3 回流与重绘#

1
// 回流（Reflow）：布局尺寸变化，性能代价大
2
// 触发条件：改变宽高、增删 DOM、改变字体、窗口缩放
3
element.style.width = '200px';  // 触发回流
4

5
// 重绘（Repaint）：外观变化不涉及布局，代价较小
6
// 触发条件：改变颜色、背景、visibility
7
element.style.color = 'red';    // 只触发重绘
8

9
// 优化：批量修改 DOM
10
// 坏做法
11
const el = document.getElementById('box');
12
el.style.width = '100px';
13
el.style.height = '100px';
14
el.style.margin = '10px';
15
// 每次修改都可能触发回流
16

17
// 好做法：使用 class
18
el.className = 'box';
19
// 或：使用 cssText
20
el.style.cssText = 'width: 100px; height: 100px; margin: 10px;';
21

22
// 好做法：文档片段
23
const fragment = document.createDocumentFragment();
24
for (let i = 0; i < 1000; i++) {
25
    const li = document.createElement('li');
26
    li.textContent = `Item ${i}`;
27
    fragment.appendChild(li);
28
}
29
list.appendChild(fragment); // 只触发一次回流

展开收起

五、这三者在博达网站群 FreeMarker 中的实际应用#

前四节是通用的前端基础。这一节专门讲——在博达网站群平台中，HTML、CSS、JS 是怎么和 FreeMarker 模板结合使用的。

5.1 FreeMarker 是”骨架增强器”#

博达的 .ftl 模板本质就是 HTML，只是多了 FreeMarker 的占位符和控制指令。浏览器最终拿到的是纯 HTML——FreeMarker 在服务端渲染时已经把变量和标签都替换掉了。

1
<#-- 博达模板中典型的 HTML 结构 -->
2
<!DOCTYPE html>
3
<html lang="zh-CN">
4
<head>
5
    <meta charset="UTF-8">
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
7
    <title>${channel.name} - ${site.name}</title>
8
    <meta name="keywords" content="${channel.keywords!site.keywords!}">
9
    <meta name="description" content="${channel.description!site.description!}">
10

11
    <#-- CSS 引入：存放在发布目录 _resources 下 -->
12
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
13
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/${channel.templateStyle!'default'}.css">
14
</head>
15
<body>
16
    <#-- 页头（公共模板片段） -->
17
    <#include "/_common/header.ftl">
18

19
    <#-- 导航栏（用 FreeMarker 循环生成 HTML） -->
20
    <nav class="main-nav">
21
        <ul>
22
            <@cms.channelList siteId="${site.id}" parentId="0">
23
                <#list channels as ch>
24
                    <li class="${(ch.id == channel.id)?string('active', '')}">
25
                        <a href="${ch.url}">${ch.name}</a>
26
                        <#if ch.hasChildren>
27
                            <ul class="sub-nav">
28
                                <@cms.channelList siteId="${site.id}" parentId="${ch.id}">
29
                                    <#list channels as sub>
30
                                        <li><a href="${sub.url}">${sub.name}</a></li>
31
                                    </#list>
32
                                </@cms.channelList>
33
                            </ul>
34
                        </#if>
35
                    </li>
36
                </#list>
37
            </@cms.channelList>
38
        </ul>
39
    </nav>
40

41
    <#-- 正文区域 -->
42
    <main class="container">
43
        <#-- 面包屑 -->
44
        <div class="breadcrumb">
45
            <a href="${site.contextPath}/">首页</a>
46
            <#list breadcrumb as crumb>
47
                &gt; <a href="${crumb.url}">${crumb.name}</a>
48
            </#list>
49
        </div>
50

51
        <#-- 内容列表 -->
52
        <div class="content-list">
53
            <@cms.contentList siteId="${site.id}" channelId="${channel.id}"
54
                              pageNo="${pageNo!1}" pageSize="${channel.pageSize!20}">
55
                <#list contents as item>
56
                    <article class="news-item">
57
                        <#if item.isTop>
58
                            <span class="tag top">置顶</span>
59
                        </#if>
60
                        <h2><a href="${item.url}">${item.title}</a></h2>
61
                        <p class="meta">
62
                            <span>${item.author!"佚名"}</span>
63
                            <span>${item.publishDate?string("yyyy-MM-dd")}</span>
64
                            <#if item.source??>
65
                                <span>来源：${item.source}</span>
66
                            </#if>
67
                        </p>
68
                        <p class="summary">${item.summary!""}</p>
69
                    </article>
70
                </#list>
71
            </@cms.contentList>
72
        </div>
73

74
        <#-- 分页 -->
75
        <#if totalPages gt 1>
76
            <div class="pagination">
77
                <#if pageNo gt 1>
78
                    <a href="${channel.url}${pageNo - 1}.html" class="prev">上一页</a>
79
                </#if>
80
                <#list 1..totalPages as p>
81
                    <a href="${channel.url}${p}.html"
82
                       class="${(p == pageNo)?string('current', '')}">${p}</a>
83
                </#list>
84
                <#if pageNo lt totalPages>
85
                    <a href="${channel.url}${pageNo + 1}.html" class="next">下一页</a>
86
                </#if>
87
            </div>
88
        </#if>
89
    </main>
90

91
    <#-- 侧边栏 -->
92
    <aside class="sidebar">
93
        <#include "/_common/sidebar.ftl">
94
    </aside>
95

96
    <#-- 页脚 -->
97
    <#include "/_common/footer.ftl">
98

99
    <#-- JS 引入 -->
100
    <script src="${site.contextPath}/_resources/js/main.js"></script>
101
    <script src="${site.contextPath}/_resources/js/${channel.templateScript!'common'}.js"></script>
102

103
    <#-- 站点统计代码（后台配置的第三方统计） -->
104
    ${site.statCode!}
105
</body>
106
</html>

展开收起

关键的对应关系：

前端基础	博达 FreeMarker 中的体现
HTML 语义标签	模板中用 `<article>`、`<nav>`、`<main>`、`<aside>` 等，FTL 负责动态填充内容
CSS 选择器与盒模型	CSS 文件放在 `_resources/css/`，模板通过 `${site.contextPath}` 引用路径
CSS Flexbox/Grid 布局	前台页面布局完全靠 CSS 实现，FTL 只负责输出结构化的 HTML
CSS 响应式设计	媒体查询同样适用，模板中可用 FreeMarker 条件判断输出不同样式类
JS DOM 操作	前台页面 JS 放在 `_resources/js/`，操作渲染后的静态 DOM
JS 事件处理	同样使用 `addEventListener`，但要注意静态页面的事件绑定时机
JS 网络请求	博达前台页面极少用 AJAX（因为是静态页面），后台管理大量使用

5.2 CSS 在博达模板中的典型用法#

路径问题是博达前端开发最需要注意的地方。由于博达支持多站点和静态发布，CSS 路径不能用绝对路径或相对路径，必须用 ${site.contextPath} 动态拼接。

1
<#-- 正确：使用 contextPath 动态路径 -->
2
<link rel="stylesheet" href="${site.contextPath}/_resources/css/main.css">
3
<link rel="stylesheet" href="${site.contextPath}/_resources/css/pages/news.css">
4

5
<#-- 错误：硬编码路径，站点迁移或更换域名后会失效 -->
6
<link rel="stylesheet" href="/_resources/css/main.css">
7
<link rel="stylesheet" href="css/main.css">

多模板风格切换是博达常见的需求，通过 FreeMarker 条件判断实现：

1
<#-- 根据栏目的模板风格配置加载不同 CSS -->
2
<#if channel.templateStyle == 'blue'>
3
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/theme-blue.css">
4
<#elseif channel.templateStyle == 'red'>
5
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/theme-red.css">
6
<#else>
7
    <link rel="stylesheet" href="${site.contextPath}/_resources/css/theme-default.css">
8
</#if>

响应式设计在博达中同样需要。因为高校和政府网站的访客大量来自手机端：

_resources/css/main.css展开收起

1
/* 博达站点的典型响应式布局 */
2

3
/* 桌面优先 */
4
.container {
5
    max-width: 1200px;
6
    margin: 0 auto;
7
    padding: 0 20px;
8
}
9

10
.main-content {
11
    display: flex;
12
    gap: 30px;
13
}
14

15
.main-content .primary {
16
    flex: 1;
17
    min-width: 0;  /* 防止 flex 溢出 */
18
}
19

20
.main-content .sidebar {
21
    width: 300px;
22
    flex-shrink: 0;
23
}
24

25
@media (max-width: 768px) {
26
    .container {
27
        padding: 0 12px;
28
    }
29

30
    .main-content {
31
        flex-direction: column;
32
    }
33

34
    .main-content .sidebar {
35
        width: 100%;
36
    }
37

38
    /* 移动端导航切换 */
39
    .main-nav ul {
40
        display: none;
41
    }
42
    .main-nav.open ul {
43
        display: block;
44
    }
45
    .nav-toggle {
46
        display: block;
47
    }
48
}
49

50
@media (max-width: 480px) {
51
    html { font-size: 14px; }
52
    .news-item h2 { font-size: 1.1rem; }
53
}

展开收起

5.3 JavaScript 在博达前台的应用场景#

博达前台是静态页面（发布后是 .html 文件），所以 JS 的使用场景和传统动态站点不同：

场景一：导航菜单交互

_resources/js/main.js展开收起

1
// 移动端导航切换
2
document.addEventListener('DOMContentLoaded', function() {
3
    var toggle = document.querySelector('.nav-toggle');
4
    var nav = document.querySelector('.main-nav');
5

6
    if (toggle && nav) {
7
        toggle.addEventListener('click', function() {
8
            nav.classList.toggle('open');
9
        });
10
    }
11
});
12

13
// 高亮当前页面的导航项
14
document.addEventListener('DOMContentLoaded', function() {
15
    var currentPath = window.location.pathname;
16
    document.querySelectorAll('.main-nav a').forEach(function(link) {
17
        if (link.getAttribute('href') === currentPath) {
18
            link.classList.add('active');
19
        }
20
    });
21
});

展开收起

场景二：图片懒加载

博达站点通常有大量图片，懒加载可以显著提升性能：

1
// 利用 IntersectionObserver 实现图片懒加载
2
document.addEventListener('DOMContentLoaded', function() {
3
    var lazyImages = document.querySelectorAll('img[data-src]');
4

5
    if ('IntersectionObserver' in window) {
6
        var observer = new IntersectionObserver(function(entries) {
7
            entries.forEach(function(entry) {
8
                if (entry.isIntersecting) {
9
                    var img = entry.target;
10
                    img.src = img.dataset.src;
11
                    img.removeAttribute('data-src');
12
                    observer.unobserve(img);
13
                }
14
            });
15
        });
16

17
        lazyImages.forEach(function(img) {
18
            observer.observe(img);
19
        });
20
    } else {
21
        // 降级处理：直接加载所有图片
22
        lazyImages.forEach(function(img) {
23
            img.src = img.dataset.src;
24
        });
25
    }
26
});

展开收起

场景三：搜索框自动补全（少量场景使用）

博达前台搜索通常是 GET 提交到搜索页面，但有些站点会做 AJAX 搜索建议：

1
// 搜索建议（需要后端提供 JSON API）
2
var searchInput = document.querySelector('.search-input');
3
var suggestBox = document.querySelector('.search-suggestions');
4

5
if (searchInput) {
6
    var debounceTimer;
7
    searchInput.addEventListener('input', function() {
8
        clearTimeout(debounceTimer);
9
        var keyword = this.value.trim();
10

11
        if (keyword.length < 2) {
12
            suggestBox.innerHTML = '';
13
            suggestBox.style.display = 'none';
14
            return;
15
        }
16

17
        debounceTimer = setTimeout(function() {
18
            fetch('/api/search/suggest?q=' + encodeURIComponent(keyword))
19
                .then(function(res) { return res.json(); })
20
                .then(function(data) {
21
                    if (data.length > 0) {
22
                        suggestBox.innerHTML = data.map(function(item) {
23
                            return '<div class="suggest-item">' + item.title + '</div>';
24
                        }).join('');
25
                        suggestBox.style.display = 'block';
26
                    } else {
27
                        suggestBox.style.display = 'none';
28
                    }
29
                });
30
        }, 300);
31
    });
32

33
    // 点击外部关闭建议框
34
    document.addEventListener('click', function(e) {
35
        if (!e.target.closest('.search-wrap')) {
36
            suggestBox.style.display = 'none';
37
        }
38
    });
39
}

展开收起

场景四：TAB 切换

博达前台常用 TAB 切换展示不同分类的内容：

1
<#-- 模板中的 TAB 结构 -->
2
<div class="tab-wrap">
3
    <div class="tab-nav">
4
        <a class="tab-item active" data-tab="notice">通知公告</a>
5
        <a class="tab-item" data-tab="news">新闻动态</a>
6
        <a class="tab-item" data-tab="download">下载中心</a>
7
    </div>
8
    <div class="tab-content">
9
        <div class="tab-panel active" id="tab-notice">
10
            <@cms.contentList siteId="${site.id}" channelId="1" pageSize="10">
11
                <#list contents as item>
12
                    <li><a href="${item.url}">${item.title}</a></li>
13
                </#list>
14
            </@cms.contentList>
15
        </div>
16
        <div class="tab-panel" id="tab-news">
17
            <@cms.contentList siteId="${site.id}" channelId="2" pageSize="10">
18
                <#list contents as item>
19
                    <li><a href="${item.url}">${item.title}</a></li>
20
                </#list>
21
            </@cms.contentList>
22
        </div>
23
        <div class="tab-panel" id="tab-download">
24
            <@cms.contentList siteId="${site.id}" channelId="3" pageSize="10">
25
                <#list contents as item>
26
                    <li><a href="${item.url}">${item.title}</a></li>
27
                </#list>
28
            </@cms.contentList>
29
        </div>
30
    </div>
31
</div>

展开收起

1
// TAB 切换
2
document.querySelectorAll('.tab-nav').forEach(function(nav) {
3
    nav.addEventListener('click', function(e) {
4
        var target = e.target.closest('.tab-item');
5
        if (!target) return;
6

7
        // 切换 TAB 高亮
8
        nav.querySelectorAll('.tab-item').forEach(function(item) {
9
            item.classList.remove('active');
10
        });
11
        target.classList.add('active');
12

13
        // 切换内容面板
14
        var tabId = 'tab-' + target.dataset.tab;
15
        var content = target.closest('.tab-wrap').querySelector('.tab-content');
16
        content.querySelectorAll('.tab-panel').forEach(function(panel) {
17
            panel.classList.remove('active');
18
        });
19
        document.getElementById(tabId).classList.add('active');
20
    });
21
});

展开收起

5.4 博达模板中 CSS/JS 的发布与缓存#

这是博达开发的常见坑。修改了 CSS 或 JS 文件后，浏览器可能缓存了旧版本，导致前台看不到修改效果。

方案一：版本号参数（推荐）

1
<#-- 在模板中给 CSS/JS 加版本号 -->
2
<#-- 版本号可以从站点配置中读取，或用时间戳 -->
3
<link rel="stylesheet"
4
      href="${site.contextPath}/_resources/css/main.css?v=${site.staticVersion!'20260601'}">
5
<script src="${site.contextPath}/_resources/js/main.js?v=${site.staticVersion!'20260601'}"></script>

每次修改静态资源后，在后台更新 staticVersion 的值，所有引用自动刷新缓存。

方案二：文件名哈希（自动化程度高）

如果能修改博达的发布流程，可以在发布时对 CSS/JS 文件做哈希命名：

1
<#-- 使用哈希文件名，修改后文件名自动变化 -->
2
<link rel="stylesheet"
3
      href="${site.contextPath}/_resources/css/main.${staticHash('main.css')}.css">

5.5 博达后台管理中的 JS#

博达后台（JSP 页面）比前台用到了更多的 JS，包括：

场景	技术	说明
栏目树展开/折叠	原生 JS / jQuery	树形控件操作
资料批量操作	AJAX	批量删除、移动、发布
模板在线编辑	CodeMirror / Monaco	代码编辑器
文件上传	FormData + AJAX	附件上传带进度条
富文本编辑	CKEditor / UEditor	资料正文编辑
数据表格排序	原生 JS	列表排序
弹窗/对话框	自定义 JS	确认、提示、警告

后台 JSP 页面中典型的 AJAX 请求：

1
<script>
2
function batchPublish() {
3
    var ids = [];
4
    document.querySelectorAll('input[name="ids"]:checked').forEach(function(cb) {
5
        ids.push(cb.value);
6
    });
7

8
    if (ids.length === 0) {
9
        alert('请选择要发布的内容');
10
        return;
11
    }
12

13
    if (!confirm('确定发布选中的 ' + ids.length + ' 条内容？')) {
14
        return;
15
    }
16

17
    // 发送发布请求
18
    fetch('${pageContext.request.contextPath}/admin/content/batchPublish', {
19
        method: 'POST',
20
        headers: { 'Content-Type': 'application/json' },
21
        body: JSON.stringify({ ids: ids })
22
    })
23
    .then(function(res) { return res.json(); })
24
    .then(function(data) {
25
        if (data.code === 200) {
26
            alert('发布任务已提交，请在发布队列查看进度');
27
            location.reload();
28
        } else {
29
            alert('操作失败：' + data.message);
30
        }
31
    })
32
    .catch(function() {
33
        alert('网络错误');
34
    });
35
}
36
</script>

展开收起

5.6 四者的关系总结#

在博达模板开发中，四者的分工非常清晰：

1
FreeMarker（服务端渲染）
2
    │ 生成静态 HTML
3
    ▼
4
HTML（结构骨架）────── CSS（样式皮肤）
5
    │
6
    └──── JS（浏览器端交互）

FreeMarker 在服务器上运行，生成最终的 HTML 文件。它负责把数据库中的栏目、资料数据填入 HTML 模板，输出纯静态页面。
HTML 是 FreeMarker 的输出格式，也是浏览器接收的内容。FreeMarker 的标签（<@cms.channelList> 等）最终都会被替换成纯 HTML。
CSS 完全不变，直接放在 _resources/css/ 下由 HTML 引用。FreeMarker 只负责输出正确的 <link> 标签和路径。
JS 同样不变，放在 _resources/js/ 下。但要注意：博达前台页面是静态的，JS 只做纯客户端的交互增强，不依赖后端接口（搜索等少数场景除外）。后台管理 JSP 页面中的 JS 则大量使用 AJAX 与后端交互。

理解了这个分工，你就能在博达模板开发中清楚地判断——某个功能应该用 FreeMarker 标签实现，还是写在 HTML/CSS/JS 里。