SYS.NOTE // 注意

欢迎接入。按键盘左上角的 `（或 Ctrl + K）可以打开站内终端，输入 help 看看能做什么。

这里是 RichZDS 的个人博客。GitHub 上的签名是「最尊重模块化的选手」，所以这个站点本身也按模块拆开：内容、生成、样式、动效、部署，各管各的。

这里会写什么#

GitHub 上的项目大概分这几条线，博客也按这几条线来写：

这个站是怎么搭的#

整个博客没有用框架，也没有 node_modules：

richzds-blog/
├─ content/posts/     # 文章：Markdown + frontmatter
├─ src/               # 生成器：Markdown 渲染、代码高亮、页面模板、GitHub 数据
├─ static/            # 样式、脚本、字体
├─ build.mjs          # node build.mjs → dist/
└─ scripts/deploy.sh  # 构建 + wrangler pages deploy

• 生成：build.mjs 读取 content/posts/*.md，用自己写的 Markdown 渲染器转成 HTML。代码高亮也在构建时做完，浏览器里不跑高亮脚本。
• 数据：「项目矩阵」和「技能芯片」是构建时从 GitHub API 拉的，缓存在 data/github.json，12 小时内不重复请求。
• 动效：数字雨是一张 <canvas>，切到后台会暂停；故障字、扫描线、霓虹闪烁全是 CSS；系统开了「减少动态效果」时会自动关掉。
• 体积：两个字体子集加起来约 25 KB，CSS 和 JS 都是手写的，页面不加载任何第三方资源。

写一篇新文章#

在 content/posts/ 下新建一个 .md 文件：

---
title: 文章标题
date: 2026-10-01 20:00
tags: [Go, 并发]
summary: 一句话摘要，会出现在卡片和 RSS 里
---

正文从这里开始。

然后：

npm run dev       # 本地预览 http://localhost:4173，改了文件自动重建
npm run deploy    # 构建并发布到 Cloudflare Pages

一些彩蛋#

• 终端里试试 neofetch、theme pink、rain off；
• 在页面上（不是终端里）按一遍 ↑↑↓↓←→←→BA；
• 首页天际线上那块竖着的霓虹招牌，写的就是这个站的主题。

接下来几篇会把 GitHub 上的项目挨个拆开讲。发现 bug 或者有想法，欢迎到 GitHub 提 issue。

总览#

后端 go.mod 里的主要依赖：

• gogf/gf/v2 v2.9.5：Web 框架，自带 ORM、配置、日志和代码生成；
• minio-go/v7：上传文件到 MinIO；
• rabbitmq/amqp091-go：连接 RabbitMQ；
• patrickmn/go-cache：进程内缓存；
• jordan-wright/email：发邮件；
• brianvoe/gofakeit/v6：cmd/seeder 用它造测试数据。

前端是 Vue 3 + Vite + Ant Design Vue，帖子编辑器用的是 md-editor-v3，请求代码由 npm run swagger:generate（zerone api）根据接口文档生成。

GoFrame 的分层#

GoFrame 的单仓库模板把一个接口拆成几层，这个项目基本照着来：

Backend/
├─ api/            # 请求 / 响应结构体，按模块和版本分：api/forum/v1/...
├─ internal/
│  ├─ controller/  # 接收请求，调用 service
│  ├─ service/     # 接口定义
│  ├─ logic/       # 接口实现：Forum / chat / room / user / trace ...
│  ├─ dao/         # 数据访问，由 gf gen dao 生成
│  └─ model/       # 数据库实体、业务模型
└─ manifest/       # 配置、SQL、Docker、部署清单

logic 里的每个模块在 init() 里把自己注册到 service：

type sRoom struct{}

func New() *sRoom {
	return &sRoom{}
}

func init() {
	service.RegisterRoom(New())
}

这样 controller 只依赖 service 接口，不关心实现在哪。要换实现、写测试，只动一层。

业务模块基本对应游戏里的概念：

• forum：版块、帖子、评论；
• room：跑团房间，配合下面的 WebSocket 聊天室；
• department：三角机构的分部，记录分部名称、经理、地址、散逸端数量，还有一个「天气」字段；
• containment：收容库，记录异常体、负责的特工、所属散逸端；
• trace：按用户、角色、部门查询红 / 黄 / 蓝三条轨迹。

多人聊天室：WebSocket + RabbitMQ#

聊天室的设计文档（Backend/docs/CHAT_WEBSOCKET.md）写得很清楚：

1. 前端连接 ws://host/ws/chat，可以用 ?token=xxx 带上 JWT；
2. 客户端发送 join / leave / chat 三种消息，带上 roomId、userId、nickname、roleName；
3. 后端把消息发布到 RabbitMQ 的 chatroom_broadcast fanout 交换器；
4. 每个后端实例绑定一条独立队列，消费到消息后，推给本实例里在这个房间的 WebSocket 连接。

消息格式：

{
  "roomId": "1",
  "userId": "123",
  "nickname": "用户昵称",
  "roleName": "角色名",
  "message": "消息内容",
  "type": "join|leave|chat",
  "time": 1710000000000
}

为什么要绕一圈 RabbitMQ？因为 WebSocket 连接是有状态的。用户 A 连在实例 1，用户 B 连在实例 2，实例 1 收到 A 的消息，在本地找不到 B。fanout 交换器把每条消息复制给所有实例，每个实例只负责推给自己手上的连接，后端就能水平扩展了。

骰子与「三重升华」#

Backend/utils/Dice.go 支持 4、8、10、12、20、24、30、100 面骰。另一个函数 Chaos 把不是 3 的点数加起来，恰好出现三个 3 时直接返回 0，注释写的是「三重升华」：

func Chaos(dice []int) (sum int) {
	// 如果 dice 里面有三个三，sum 为 0
	trible := 0
	for i := 0; i < len(dice); i++ {
		if dice[i] != 3 {
			sum += dice[i]
		}
		if dice[i] == 3 {
			trible++
		}
	}
	if trible == 3 { // 三重升华
		return 0
	}
	return sum
}

顺手记一个可以改进的地方：Dice 每次调用都会执行 rand.Seed(time.Now().UnixNano())。Go 1.20 起 rand.Seed 已经弃用，全局随机源在启动时会自动播种。项目用的是 Go 1.25，可以直接删掉这一行，或者换成 math/rand/v2：

import "math/rand/v2"

func Dice(num, side int) []int {
	result := make([]int, num)
	for i := range result {
		result[i] = rand.IntN(side) + 1
	}
	return result
}

文件上传：MinIO#

帖子图片和资料文件存在 MinIO，配置在 manifest/config/config.yaml：

minio:
  endpoint: "localhost:9000"
  accessKey: "minioadmin"
  secretKey: "minioadmin"
  bucket: "trangleagent"
  useSSL: false

图片要能被直接访问，需要给 bucket 配一条只读的公开策略（只放开 s3:GetObject）。

一键部署#

# 构建并启动所有服务
docker compose up -d --build

# 看后端日志
docker compose logs -f backend

第一次启动时，MySQL 会自动执行 Backend/manifest/sql/ 下的初始化脚本；MinIO 要先在控制台建好 trangleagent bucket；注册第一个用户就能登录。

小结#

• GoFrame 的 api → controller → service → logic → dao 让每层只关心一件事；
• WebSocket 有状态，多实例广播交给 RabbitMQ 的 fanout 交换器；
• 依赖组件（MQ、对象存储）都有降级或默认配置，本地开发成本低；
• 骰子这类小工具函数值得补单元测试，顺便把弃用的 API 换掉。

前端的早期版本在 TrangleAgentWeb 仓库。

玩法#

每一关是一个目录，里面有 README.md（场景和任务）、main.go（有问题的代码）和 main_test.go（验收测试）：

1. 按顺序进一关，读 README；
2. 运行前先写下预测：结果对不对？每次都一样吗？
3. 从项目根目录运行；
4. 只改 main.go，不许改测试来绕过要求；
5. 普通测试和竞态检测都要通过。

go run ./level01
go run -race ./level01
go test -v ./level01
go test -race -v ./level01

求助也分了三档：「给我第 N 关一个提示」只给方向；「讲讲第 N 关的思路」解释机制但不给代码；「解答第 N 关」才给完整方案。拿去配合 AI 助手用正合适：想让它帮忙，又不想被剧透。

关卡地图#

注意第 06 和第 10 关：starter 代码的测试一开始就是绿的。06 关还要你人工观察读多写少的场景并改进，10 关要实现优化并用多轮 benchmark 对比。测试通过不等于学完了。

挑两关细看#

Level 03：少掉的积分#

20 名计分工人同时处理得分事件，每人登记 5,000 次一分，理论总分 100,000，但程序时不时会少分。

问题出在 score += points 不是一步完成的，而是读取、计算、写回三步。两个 goroutine 交错执行时：

工人 A 读到 score = 41     工人 B 读到 score = 41
工人 A 算出 42             工人 B 算出 42
工人 A 写回 42             工人 B 写回 42   ← 丢了一分

这就是「丢失更新」。关卡 README 里有一句值得反复读：

普通运行偶尔得到正确分数并不能证明安全；反过来，错误总分展示了结果问题，却不能替代竞态检测。

所以验收标准是两条同时满足：结果精确等于 100,000，并且 go test -race 没有报告。也不能靠减少工人或者改成串行来「修好」，要找出最小的正确临界区。

Level 07：相反方向的转账#

A 转 B、B 转 A 几乎同时发生。代码先锁付款方、再锁收款方，于是两个 goroutine 各拿一把锁、互相等对方，死锁了。

死锁要同时满足四个条件：互斥、持有并等待、不可抢占、循环等待。前三个是锁本身的性质，能拆掉的只有「循环等待」。这一关的要求是：

• 不按「付款方 / 收款方」的角色决定加锁顺序，而是按系统内唯一、不可变的账户 ID 建立全局顺序；
• 拿到两把锁之后按业务方向改余额，再按加锁的相反顺序解锁；
• 自己转给自己要单独处理：Go 的 sync.Mutex 不可重入，同一把锁锁两次会把自己卡死。

测试里设了 500 毫秒超时，失败时会明确报超时，而不是让整个测试进程挂住。两把锁之间那 20 毫秒的暂停只是为了稳定复现危险的交错，它不是根因，也不能靠删掉它来「修复」。

为什么值得这么练#

• 先预测，逼你在脑子里把调度过一遍，比直接看答案记得牢；
• -race 把「偶尔出错」变成「每次都报错」，这是 Go 并发最好用的工具；
• 不给答案、分级提示，卡住本身就成了学习的一部分。

仓库地址：RichZDS/golangexe。建议从第一关开始，别跳关。

技术栈#

三种角色，一条流水线#

求职者：注册 → 写简历 → 浏览岗位 → 投递 → 查看进度 → 面试
Boss  ：维护公司 → 发布岗位 → 处理投递（接受 / 拒绝 / 待定）→ 安排面试
管理员：用户管理 → 全局投递管理

数据库里对应七张核心表：user、company、job_posting、resume、application（投递）、boss_application_decision（投递处理）、interview（面试）。前端路由也按角色分：/user/resumes、/user/applications 是求职者的，/boss/company、/boss/applications 是 Boss 的，/admin/applications 是管理员的。

权限：一个注解 + 一个切面#

接口上标一个 @AuthCheck，写明需要的角色：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface AuthCheck {
    String mustRole() default "";
}

@AuthCheck(mustRole = UserConstant.ADMIN_ROLE)

AuthInterceptor 用 @Around("@annotation(authCheck)") 拦截这些方法：取当前登录用户，被封禁（status == 0）的直接拒绝，管理员直接放行，需要 Boss 权限的接口只放 Boss 进去。

权限逻辑集中在一个地方，controller 里一行注解就够了，这就是切面的价值。

AI 简历优化#

ResumeController 里有一个 POST .../ai/optimize 接口，交给 AiServiceImpl 处理。它用 Spring AI 的 ChatClient 包了一层 DeepSeek：

ChatClient chatClient = ChatClient.builder(deepSeekChatModel).build();
String response = chatClient.prompt()
        .system(SYSTEM_PROMPT)
        .user(userMessage)
        .call()
        .content();

系统提示词把模型设定成「有 10 年以上招聘经验的简历分析师」，给了三条优化原则：

1. 标题简洁有力，突出核心职位和关键技能；
2. 个人摘要控制在 100–200 字，突出核心竞争力；
3. 详细内容用 STAR 法则（情境、任务、行动、结果）描述经历，尽量量化。

还特别要求「保持内容真实，在原有基础上润色」，最后规定只返回 JSON：

{
  "resumeTitle": "优化后的简历标题",
  "summary": "优化后的个人摘要",
  "content": "优化后的详细内容"
}

模型不一定听话，经常会把 JSON 包在 Markdown 代码块里。所以 extractJson 会先找 ```json 代码块，把里面的内容抠出来，再交给 Jackson 解析。解析失败统一抛 BusinessException，前端拿到的是可读的错误信息，而不是一串堆栈。

可以继续打磨的地方#

• 封禁状态的检查写在 mustRole 分支里，没标 @AuthCheck 的接口不会经过这一步。如果希望所有登录接口都拦住被封账号，可以把检查挪到 getLoginUser 里统一做。
• ChatController 里还留着 /chat/test、/chat/model 两个调试接口，上线前最好删掉或者加上权限。
• AI 返回的原始内容会整段打进 info 日志，简历里有个人信息，生产环境建议降到 debug 或者脱敏。

小结#

这个项目把一个中等规模的 CRUD 系统做全了：三种角色、七张表、完整的投递流程，再用注解和切面把权限收到一处。AI 部分最有意思的不是调接口，而是怎么让模型稳定地吐出能被程序解析的 JSON。

结构#

langchain_demo/
├─ frontend/                 # Vue 3 + Ant Design Vue，端口 9000
│  └─ src/
│     ├─ App.vue             # 生成指导、表单、结果与历史
│     ├─ api.ts              # REST API 客户端
│     └─ styles.css
└─ backend/                  # FastAPI，端口 9001
   ├─ app/
   │  ├─ routers/            # RESTful 路由
   │  ├─ services/           # AI 生成服务
   │  ├─ repository.py       # 内存文章仓库
   │  └─ main.py
   ├─ scripts/export_openapi.py
   └─ tests/

开发时 Vite 把 /api 代理到 http://127.0.0.1:9001，前后端各跑各的端口，不用处理跨域。

REST API#

「生成」被建模成创建一个文章资源：POST /articles 成功返回 201 Created；AI 服务出错时返回 502 Bad Gateway，并附上 GENERATION_FAILED 错误码。上游坏了就说上游坏了，这个状态码选得很准。

FastAPI 自带 Swagger（/docs）和 ReDoc（/redoc），scripts/export_openapi.py 还能把 OpenAPI JSON 导出来，给其他工具用。

两种生成模式#

ArticleGenerator.generate() 根据环境变量 AI_MODE 选路：

async def generate(self, request: ArticleCreate) -> GeneratedArticle:
    if settings.ai_mode.lower() == "openai":
        if not settings.ai_api_key:
            raise GenerationError("AI_MODE=openai 时必须配置 AI_API_KEY")
        return await self._generate_with_openai(request)
    return self._generate_demo(request)

• demo 模式（默认）：不调任何模型，用模板按「为什么值得关注 → 先搭框架 → 可执行步骤 → 常见误区 → 结语」拼出一篇结构完整的文章。没有 Key 也能完整演示前后端流程，写测试也不用 mock 网络。
• openai 模式：用 httpx 直接请求 {AI_BASE_URL}/chat/completions。AI_BASE_URL 换成任何 OpenAI 兼容的服务都行。

$env:AI_MODE = "openai"
$env:AI_API_KEY = "你的密钥"
$env:AI_BASE_URL = "https://api.openai.com/v1"
$env:AI_MODEL = "gpt-4.1-mini"

提示词怎么写#

系统消息只做一件事，约束输出格式：

你是一名专业中文编辑。输出严格的 JSON 对象，字段必须为
title、abstract、outline（字符串数组）、content（Markdown 全文）。

请求里还带了 response_format: {"type": "json_object"}。用户消息把表单里的每个字段逐条列出来，最后给出硬性要求：

要求：标题有吸引力，摘要不超过 120 字；正文使用 Markdown 二级标题分段，
逻辑完整、信息具体、有开头和结语，不编造数据或来源。

「不编造数据或来源」这一句很重要。写作类应用最大的风险不是文笔差，而是一本正经地编参考文献。

返回之后，_parse_json 先用正则剥掉可能出现的 ```json 代码块，再 json.loads。缺字段、类型不对、JSON 坏掉，全部收敛成 GenerationError，路由层再翻译成 502。

字数怎么数#

中文按字、英文按词：

def count_words(text: str) -> int:
    """中文按字、英文按词统计，提供接近阅读习惯的字数。"""
    return len(re.findall(r"[㐀-鿿]|[A-Za-z0-9]+", text))

下一步#

• 仓库名叫 langchain_demo，但目前的实现没有引入 LangChain，而是用 httpx 直接调接口。先用最少的依赖跑通，后面再把 PromptTemplate、输出解析器之类换成 LangChain 的组件，是个稳妥的顺序；
• 历史记录存在内存里（ArticleRepository），服务一重启就清空。换成 SQLite 或 MySQL 时只需要替换仓库实现，路由层不用动，这也是当初把仓库单独抽出来的好处；
• 长文生成可以改成流式返回（SSE），体验会好很多。

这个项目一开始叫「消费管理系统」：管理员管客户和消费记录、看统计报表，客户查自己的消费。后来后端又长出了课程、预约、教练、器材、场地、员工这些模块，成了一个运动场馆管理系统。模块多了以后，分层是否清楚会直接决定项目能不能继续写下去。

分层#

前端 README 里画过一张规划：controller → logic → service → dao → do → dto → vo。落到后端代码里是这样的：

com.zds.sports
├─ controller/      # HTTP 入口：参数、状态码、接口文档
├─ service/         # 业务接口
│  └─ impl/         # 业务实现（继承 MyBatis-Plus 的 ServiceImpl）
├─ dao/             # Mapper，只管读写数据库
├─ domain/entity/   # DO：和表一一对应，比如 ConsumeRecordDO
├─ model/dto/       # DTO：入参，比如 CreateRecordDTO / UpdateRecordDTO
├─ model/vo/        # VO：出参，比如 RecordVO / PageResultVO
├─ convert/         # MapStruct 转换器
└─ config/          # 跨域、Jackson、分页、全局异常、自动填充

规划里的 logic 层（跨多个 service 的编排）暂时没有单独拆出来。业务还简单的时候，编排直接写在 service 里就够了，等出现一个接口要协调好几个领域的情况再拆也来得及。

三种对象，三条边界#

为什么不一个实体类用到底？因为三者变化的原因不一样：

• 表加了一列审计字段，不应该让前端看到，所以 VO 和 DO 要分开；
• 创建和更新需要的字段、校验规则不一样，所以 Create / Update 各有一个 DTO；
• 前端想要「客户名」而不是「客户 ID」，这种展示需求只改 VO 和转换器，不碰表结构。

入参 DTO 用 Jakarta Validation 把关：

@Data
public class CreateRecordDTO {
    @NotNull
    private Long customerId;
    @NotNull
    private BigDecimal amount;
    @NotNull
    private String category;
    private String remark;
    @NotNull
    private String paidAt;
}

金额用的是 BigDecimal 而不是 double，写和钱有关的代码时这一点不能省。

转换交给 MapStruct#

对象分开以后，最烦的是互相拷字段。MapStruct 在编译期生成转换代码，不用反射，出错时编译就报：

@Mapper(componentModel = "spring",
        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface RecordMapStruct {
    @Mapping(target = "customerName",
             expression = "java(recordDO.getCustomer() != null ? recordDO.getCustomer().getName() : null)")
    RecordVO toVO(ConsumeRecordDO recordDO);

    @Mapping(target = "paidAt", expression = "java(parseDateTimeFlexible(createRecordDTO.getPaidAt()))")
    ConsumeRecordDO toDO(CreateRecordDTO createRecordDTO);

    @Mapping(target = "paidAt", expression = "java(parseDateTimeFlexible(updateRecordDTO.getPaidAt()))")
    void updateDO(UpdateRecordDTO updateRecordDTO, @MappingTarget ConsumeRecordDO recordDO);
}

NullValuePropertyMappingStrategy.IGNORE 很关键：更新时 DTO 里没传的字段是 null，这个策略保证它不会把数据库里原来的值覆盖掉，局部更新就这样实现了。

有了转换器，service 里的代码只剩业务本身：

public RecordVO createRecord(CreateRecordDTO createRecordDTO) {
    ConsumeRecordDO recordDO = recordMapStruct.toDO(createRecordDTO);
    this.save(recordDO);
    return recordMapStruct.toVO(recordDO);
}

DTO 进，DO 落库，VO 出，一眼能看完。

controller 保持薄#

@PostMapping
@ResponseStatus(HttpStatus.CREATED)
@Operation(summary = "Create a new consumption record")
public RecordVO createRecord(@Valid @RequestBody CreateRecordDTO createRecordDTO) {
    return consumeRecordService.createRecord(createRecordDTO);
}

controller 只做三件事：声明路由和状态码（创建返回 201，删除返回 204）、触发校验（@Valid）、把活交给 service。校验失败由 GlobalExceptionHandler 统一处理，把字段错误拼成一条可读的消息返回 400；其他未捕获的异常也会记日志，统一返回 500。

前端也分层#

前端是 React + Ant Design + ECharts，同样按职责拆开：

src/
├─ pages/        # Admin/Customers、Admin/Records、Admin/Reports、Customer/Records
├─ components/   # Table、Form、Chart（统一封装 ECharts）
├─ services/     # Axios 封装，baseURL 来自 VITE_API_BASE
└─ routes/       # 路由配置

图表组件只收一个 options：

<Chart options={options} style={{ height: 360 }} />

页面只管准备数据，怎么初始化 ECharts、窗口变化时怎么 resize，都关在组件里面。

小结#

模块化不是为了目录好看，而是为了改一处的时候，只需要改一处：

• 改表结构，只动 DO 和转换器；
• 改返回格式，只动 VO 和转换器；
• 改校验规则，只动 DTO；
• 换图表库，只动 Chart 组件。

SDUT 这个仓库想解决的就是这件事。README 里写道：

我为这一年一年，这么多人孤军奋战的重复劳动感到不平。

我希望只要是前人走过的弯路，后人就不必再走。

这段前言借鉴了浙大学习指南 zju-icicles，README 里也注明了出处。

仓库怎么组织#

按学期分目录，每门课一个 README，资料和经验放在一起：

SDUT/
├─ 大一下/
│  └─ README.md          # 本学期科目总览
└─ 大二上/
   ├─ 离散数学/          # 经验 + 思维导图
   ├─ 线性代数（B）/
   ├─ 面向对象/          # 经验 + 往年试卷
   ├─ 马克思主义原理/
   └─ 操作系统.rar

仓库在 GitHub 上收到了 3 个 star，数字不大，但对一个面向单个专业的资料库来说，说明真的有人在用。

各门课的经验#

下面是从各门课 README 里整理出来的建议。

大一下#

• 计算机组成原理：408 考研科目之一。学的范围比普通计科窄，难点在英语。实验课前期不难，后面几次会变难，要把实验和课本对照着学。
• 程序设计基础：上学期的进阶，从结构体一路讲到贪心和动态规划，难度直线上升。题目基本和 PTA 相关，多刷 PTA 是最直接的办法。
• 高级程序设计：全英文授课，学 Java。期末要做一个小游戏（比如纸牌游戏）并答辩。
• 计算机科学基础：全英文授课，是下学期离散数学的基础。

大二上#

• 离散数学：这学期难度最高。以定义和性质定理为主，是后面数据结构的基础。刚开始听不懂很正常，回头再看会突然开窍。老师上课强调的往年题一定要标出来，期末前讲解的那套旧卷要吃透。另外它和四六级、操作系统的考试挨得很近，要提前安排复习。
• 面向对象：整体偏难，挂科率不低。建议提前在网上找 Java 基础课补一补，再突击背一下英文术语。
• 线性代数（B）：老师会把笔记整理在语雀上，照着学就行。

为什么这种仓库值得做#

1. 信息差是能消除的。一门课的重点、考试形式、容易踩的坑，写下来只要十几分钟，却能省下后来人好几周的摸索。
2. 仓库比群聊可靠。群文件会过期，聊天记录会被刷走，Git 仓库有目录、有历史，还能接受别人的 PR。
3. 写下来也是复盘。给别人写经验的时候，会重新想一遍这门课到底在讲什么。

README 里也写了：如果有文件侵犯了谁的权益，可以联系作者删除。分享资料的同时尊重版权，这一条不能少。

如果你也是 SDUT 的同学，欢迎去仓库补充你那一届的经验，点个 star 也好。