工程质量¶

主要内容

工程规范提高可读性、可维护性和协作效率。测试给行为建立可重复验证。Code Review 优先看 bug、边界、安全和测试。AI 生成代码尤其要警惕不存在 API、错误处理缺失和安全配置过宽。

参考文档¶

工程规范.md、测试方法论.md、代码审核与幻觉识别.md、上下文管理和代码质量.md、设计模式.md

知识地图¶

概念：先理解这个模块为什么存在。
工具：再看它通过哪些工具落地。
场景：最后判断什么时候该用，什么时候不该用。

核心整理¶

工程规范提高可读性、可维护性和协作效率。测试给行为建立可重复验证。Code Review 优先看 bug、边界、安全和测试。AI 生成代码尤其要警惕不存在 API、错误处理缺失和安全配置过宽。

我在整理这部分时的重点是把工具放回工程场景，而不是孤立记名词。一个工具出现，通常是为了解决某种复杂度：协作复杂度、上下文复杂度、运行环境复杂度、系统规模复杂度或信息获取复杂度。

学习笔记¶

先读 Why，确认它解决的问题。
再读 What，建立概念边界。
再读 How，补命令、API、配置和实践。
最后用一个小 demo 验证。

实践清单¶

用自己的话解释本模块核心概念。
找一个最小 demo 跑通。
记录一个踩坑点。
把相关命令或配置写成可复用片段。
回看飞书原文，补齐遗漏的术语。

飞书思考题¶

什么是小驼峰命名？什么是 snake_case？¶

小驼峰如 userName，首词小写后续首字母大写；snake_case 如 user_name，用下划线连接小写单词。

Commit 中 feat、fix 等分别表示什么？¶

feat 表示功能新增，fix 表示修复，docs 表示文档，refactor 表示重构，test 表示测试，chore 表示工具和依赖等杂项。

工程规范为什么重要¶

飞书文档提到工程规范能提高可读性、可维护性和协作效率。我补充一点：规范也是给未来的自己和 AI 看的。项目结构越稳定，AI 越容易理解上下文，人也越容易接手。

目录结构¶

前端常见：

src/
  api/
  components/
  hooks/
  pages/
  styles/
  utils/

后端常见：

handlers/
services/
dao/
models/
config/
middlewares/

重点不是照抄目录名，而是职责清楚。

命名规范¶

命名应该表达含义，而不是表达类型废话。

不太好：

const data = [];
const handle = () => {};

更好：

const comments = [];
const handleSubmitComment = () => {};

SOLID、DRY、KISS¶

SOLID 偏面向对象设计，入门阶段先抓三个：

单一职责：一个模块最好只有一个变化原因。
开闭原则：扩展新行为尽量少改旧逻辑。
依赖反转：高层策略不要死依赖底层细节。

DRY 是不要重复逻辑，但也不要过早抽象。KISS 是保持简单，不用复杂方案炫技。

测试层次¶

飞书测试文档区分：

单元测试：函数、组件。
集成测试：模块配合，例如 API + DB。
系统测试：完整业务链路。
A/B 测试：产品策略验证。

我对全栈项目的最低要求：

后端 API 有测试。
数据库关键事务有测试。
前端关键交互能手动或自动验证。
鉴权边界必须测。

Code Review¶

Review 不只是挑风格。优先级应该是：

功能是否符合需求。
有没有安全问题。
有没有边界条件遗漏。
有没有错误处理。
有没有测试。
改动范围是否过大。
风格是否符合项目。

AI 幻觉识别¶

AI 生成代码最常见问题：

编造库 API。
忘记安装依赖。
只处理成功路径。
用不安全默认配置。
破坏已有文件结构。
把 mock 当真实数据。

应对方式：跑测试、查官方文档、看 diff、让 AI 解释改动依据。

上下文管理与质量¶

复杂重构前，先让 AI 写测试或补测试。没有测试的重构，像没有安全绳。

好的 AI 协作流程：

说明目标 -> 限定范围 -> 先写测试 -> 修改代码 -> 运行测试 -> review diff -> commit

知识卡片¶

Happy Path¶

只测试成功路径是不够的。真实项目更容易在空输入、无权限、网络失败、重复提交时出问题。

Review 粒度¶

一个 PR 太大，review 质量会下降。小而聚焦的 PR 更容易发现问题。

过早抽象¶

DRY 不代表看到两段相似代码就立刻抽象。抽象应该建立在稳定变化模式之上。