1. 项目概述：为什么“语言特定规则”不是语法糖，而是工程落地的分水岭

你有没有遇到过这样的情况：团队里三个人写同一个功能，Go 用 context.WithTimeout 做超时控制，TypeScript 用 AbortController ，Python 却还在 threading.Timer 和 signal.alarm 之间反复横跳？代码逻辑一模一样，但上线后 Go 服务稳如磐石，TS 接口偶发挂起，Python 脚本在 Linux 定时任务里跑着跑着就卡死——最后排查发现，根本不是业务逻辑错了，而是三个人对“超时”这件事的理解，压根不在同一套规则体系里。这节课讲的 Rules（下），说的正是这个被绝大多数教程跳过的硬核环节： 语言特定规则不是可有可无的补充说明，而是把抽象设计翻译成真实运行时行为的唯一桥梁 。它直接决定你的代码在生产环境里是“能跑”，还是“敢上”。关键词里反复出现的 Go、TypeScript、Python，并非随意罗列，而是当前中大型工程里最典型的三层技术栈代表：Go 承担高并发网关与微服务核心，TypeScript 主导前端交互与跨端逻辑，Python 支撑数据管道、AI 工具链与运维脚本。这三者对“规则”的实现方式天差地别——Go 用编译期强制约束+运行时 panic 拦截，TS 依赖类型系统+编译器警告+ESLint 插件链，Python 则靠文档约定+装饰器+运行时断言+mypy 静态检查组合拳。我带过 7 个不同行业的交付团队，凡是跳过“语言特定规则”这一课直接写业务的，90% 在第二迭代周期就会遭遇“规则失焦”：接口字段命名在 Go struct tag 里是 json:"user_id" ，TS interface 里却写成 userId: string ，Python dataclass 又变成 user_id: str ，API 网关一转发，字段全丢。这不是风格问题，是规则没对齐。所以这节课不讲“怎么写”，而讲“为什么必须这样写”——当你真正理解 Go 的 go.mod 语义版本规则如何防止依赖爆炸，TS 的 strictNullChecks 如何让 undefined 不再是线上事故的幽灵，Python 的 __all__ 如何控制模块级 API 边界，你才真正拿到了工程化落地的钥匙。适合谁？不是刚装完 Python 解释器的小白，而是已经能写 CRUD、正准备接手真实项目协作的开发者；不是只看文档的理论派，而是被线上 panic: send on closed channel 或 TypeError: Cannot read property 'length' of undefined 抓狂过的实战派。

2. 核心设计思路拆解：为什么不能统一用一套 ESLint 规则管所有语言？

很多人第一反应是：“既然都是规则，搞个统一配置不就完了？”我试过——三年前在一家金融科技公司，我们真用一个 YAML 文件定义了“所有语言禁止使用全局变量”“所有函数参数必须有类型声明”“所有错误必须显式处理”。结果呢？Go 代码里 var ErrInvalidToken = errors.New("token invalid") 被标红，因为 ESLint 当它是 JS 全局变量；TS 里 const [data, loading] = useState<Data[]>([]) 被报错，说数组解构没类型——可 TS 类型系统明明已经推导出来了；Python 里 def process(items: List[Dict]) -> None: 直接被 lint 工具忽略，因为它的类型注解解析器压根不认 List[Dict] 这种写法。问题出在哪？ 规则引擎的底层契约不同 。ESLint 是为 JavaScript 生态设计的 AST 解析器，它看到 Go 代码就像人看甲骨文——字形都认不全，更别说理解 defer 的执行时机或 sync.Pool 的内存复用逻辑。TypeScript 的 TSLint（已归并入 ESLint）虽然能解析 .ts 文件，但它对 declare module 的作用域规则、 namespace 与 module 的混用边界，完全依赖 TypeScript 编译器本身的 program 对象，脱离 TS Compiler API 就是空中楼阁。Python 的 pylint 或 ruff 更狠，它连 async def 函数里 await 的调用链深度都无法静态分析，必须依赖 mypy 的类型推导结果才能判断 await some_coroutine() 是否真的返回协程对象。所以“语言特定规则”的设计起点，从来不是“怎么统一”，而是“如何尊重每种语言的运行时契约”。Go 的规则必须锚定在 go vet + staticcheck 的检查点上，比如 SA1019 （使用已弃用 API）的触发条件，是 go/types 包在类型检查阶段标记的 Deprecated 字段；TS 的规则必须绑定到 typescript-eslint 的 RuleCreator 接口，其 create 方法接收的是 TSESTree.Program 节点，而节点属性 body 里的每个 TSESTree.VariableDeclaration 都携带了 typeAnnotation 属性，这才是 @typescript-eslint/no-explicit-any 能精准定位 any 类型的依据；Python 的规则则要深入 ast 模块的 ASTVisitor ，比如 ruff 的 RUF001 （未使用的导入）检测，是在 visit_ImportFrom 方法里记录所有 names ，再在 visit_Name 里比对是否被引用。这决定了我们不能把规则当配置文件来管理，而必须把它当成“语言运行时的翻译器”来设计。举个具体例子：要求“所有 HTTP 客户端请求必须设置超时”。在 Go 里，规则检查点是 http.Client 结构体的 Timeout 字段是否为零值，或者 http.NewRequestWithContext 的 context.Context 是否包含 Deadline ；在 TS 里，检查点是 fetch 调用是否包裹在 AbortSignal.timeout() 内，或 axios 实例的 timeout 配置项是否缺失；在 Python 里，则要看 requests.Session 的 timeout 参数是否传入元组 (connect_timeout, read_timeout) ，或 aiohttp.ClientSession 的 timeout 是否为 aiohttp.ClientTimeout 实例。三个检查点，指向三种完全不同的 AST 节点和运行时对象。这就是为什么“语言特定规则”必须拆开设计——不是为了增加复杂度，而是为了确保每条规则都能真正刺穿到语言的运行时肌理里去。

3. 核心细节解析与实操要点：Go、TypeScript、Python 三大规则落地的关键切口

3.1 Go 语言：从 go.mod 版本语义到 context 生命周期的硬性约束

Go 的规则之所以“硬”，是因为它把很多设计决策直接编译进了工具链。最典型的就是 go.mod 的语义化版本规则。很多人以为 v1.2.3 只是个字符串，其实 go list -m all 输出的每一行都隐含着严格契约： v0 开头的模块表示不稳定 API， v1 表示向后兼容， v2+ 必须通过 /v2 路径导入。我见过最惨的案例是某团队把 github.com/gorilla/mux v1.8.0 升级到 v1.9.0 后，所有路由中间件突然失效——查了半天发现 v1.9.0 里 mux.Router.Use() 方法签名从 func(...MiddlewareFunc) 变成了 func(MiddlewareFunc, ...MiddlewareFunc) ，破坏了 v1.x 的向后兼容承诺。但 go mod tidy 并不报错，因为 v1.9.0 仍属于 v1 大版本。真正的规则检查点在这里： go list -m -f '{{.Version}} {{.Indirect}}' github.com/gorilla/mux ，如果 Indirect 为 true ，说明它被间接依赖引入，此时必须人工确认其 Version 是否在主模块 go.mod 的 require 块中显式声明。这是第一条硬规则： 所有间接依赖必须显式提升为主依赖，并标注最小兼容版本 。第二条是 context 规则。Go 官方文档说“不要将 context 存储在结构体中”，但没人告诉你为什么。实测发现，当 context.WithCancel 创建的子 context 被存储在长生命周期 struct 里，而父 context 因超时或取消被释放后，子 context 的 Done() channel 会永远阻塞，导致 goroutine 泄漏。规则检查点是 go vet -shadow 配合自定义 staticcheck 规则：扫描所有 struct 定义，若字段类型为 context.Context 且该 struct 实例化发生在 func 作用域外（即包级变量或全局变量），则触发告警。第三条是错误处理规则。 errors.Is(err, io.EOF) 必须替代 err == io.EOF ，因为后者无法匹配包装后的错误。检查点是 go vet -printf 的 Sprintf 格式字符串分析，以及 staticcheck 的 SA1019 对 errors.New 和 fmt.Errorf 的调用链追踪。这些规则之所以有效，是因为它们全部基于 go/types 包的类型信息，而非字符串匹配——这才是 Go 规则的根基。

3.2 TypeScript：从 tsconfig.json 编译选项到 ESLint 插件链的协同防御

TypeScript 的规则是“软硬兼施”的典型。所谓“软”，是指它不阻止你写 any 或 // @ts-ignore ；所谓“硬”，是指一旦开启 strict 模式，编译器会直接拒绝生成 JS 文件。所以 TS 规则设计必须分层：编译层守底线，ESLint 层管风格，运行时层兜底。第一层是 tsconfig.json 的核心选项。 "strictNullChecks": true 不是可选开关，而是必须项——它让 string | null 和 string 成为互斥类型，避免 if (name) 这种空值判断失效。但很多人忽略了 "exactOptionalPropertyTypes": true ，它强制 interface User { name?: string } 中的 name 只能是 string | undefined ，不能是 string | null | undefined 。这个选项在对接 Go 后端时至关重要，因为 Go 的 JSON 序列化默认把零值字段设为 null ，而 TS 如果允许 null 混入，就会导致类型安全形同虚设。第二层是 ESLint。 @typescript-eslint/no-explicit-any 是基础，但真正关键的是 @typescript-eslint/consistent-type-assertions ，它强制使用 as Type 而非 <Type> 语法，因为后者在 JSX 文件中会产生歧义。更隐蔽的是 @typescript-eslint/no-misused-promises ，它能检测 if (somePromise) 这种错误用法——Promise 对象在布尔上下文中永远为 true ，但开发者本意可能是 if (await somePromise) 。第三层是运行时防御。比如要求“所有 fetch 请求必须处理网络错误”，ESLint 只能检查 catch 块是否存在，但无法判断 catch (e) { console.error(e) } 是否真的处理了错误。这时需要注入运行时钩子：在 globalThis.fetch 上做代理，捕获 TypeError: Failed to fetch 并抛出自定义 NetworkError ，再配合 try/catch 的类型守卫 if (e instanceof NetworkError) 。这三层规则像三道防火墙：编译层拦住明显错误，ESLint 层规范编码习惯，运行时层兜住漏网之鱼。

3.3 Python：从 __all__ 模块导出到 typing 运行时验证的渐进式加固

Python 的规则哲学是“信任但要验证”。它不像 Go 那样用编译器强制，也不像 TS 那样有强类型系统，而是通过约定、装饰器和运行时检查组合推进。第一条是模块级规则： __all__ 。很多人以为这只是给 IDE 提示用的，其实它是 from module import * 的唯一权威来源。我维护的一个数据处理库曾因忘记更新 __all__ ，导致内部工具函数 __parse_config() 被意外导出，下游项目直接调用，结果我们重构时删掉该函数，所有调用方集体崩溃。规则检查点是 pylint 的 W0614 （未在 __all__ 中声明的导入），但更可靠的是 ruff 的 RUF100 ，它能扫描整个模块的 def 和 class 定义，对比 __all__ 列表，缺失项直接报错。第二条是类型注解规则。Python 3.12 引入了 typing.TypeAlias ，但很多团队还在用 from typing import Dict, List 。规则要求：所有新代码必须使用 dict[str, int] 这种内联语法，禁用 Dict[str, int] 。检查点是 ruff 的 UP006 （ typing.Dict 已弃用），它基于 AST 的 Subscript 节点分析，当 value.id 为 Dict 且 slice 是 Tuple 时触发。第三条是运行时验证。比如要求“所有数据库查询函数必须接受 session: AsyncSession 参数”，光靠类型注解 def query(session: AsyncSession) 不够，因为调用方可能传入 None 。这时要用 @validate_arguments 装饰器（来自 pydantic ），在函数入口自动检查 session 是否为 AsyncSession 实例。更进一步，可以结合 dataclasses.field(default_factory=lambda: get_session()) 实现依赖注入，把规则从“必须传参”升级为“自动提供”。这种渐进式加固，正是 Python 规则设计的精髓：不追求一步到位的强约束，而是用最小侵入的方式，把规则嵌入到开发者自然的工作流里。

4. 实操过程与核心环节实现：手把手搭建跨语言规则检查流水线

4.1 环境初始化：为三种语言分别构建可复现的检查基座

先解决最实际的问题：怎么让规则检查在本地和 CI 环境里行为一致？答案是放弃“全局安装”，改用“项目级锁定”。Go 用 go install golang.org/x/tools/cmd/goimports@v0.14.0 ，而不是 brew install goimports ——因为 Homebrew 安装的版本可能滞后，而 go install 会把二进制文件放在 $GOPATH/bin 下，通过 PATH 注入，且版本号精确到 commit。TypeScript 用 npx eslint@8.57.0 --version 而非全局 eslint -v ，因为 npx 会优先查找 package.json 的 devDependencies ，确保团队成员用的 ESLint 版本完全一致。Python 更激进：用 pipx install ruff==0.5.4 ， pipx 会为每个工具创建独立虚拟环境，彻底隔离依赖冲突。初始化命令如下：

# Go 环境
go install golang.org/x/tools/cmd/goimports@v0.14.0
go install honnef.co/go/tools/cmd/staticcheck@2024.1.3

# TypeScript 环境
npm init -y
npm install --save-dev eslint@8.57.0 @typescript-eslint/eslint-plugin@6.21.0 @typescript-eslint/parser@6.21.0 typescript@5.4.5

# Python 环境
pipx install ruff==0.5.4
pipx install mypy==1.10.0

关键细节： staticcheck 的版本号 2024.1.3 不是语义化版本，而是年份+季度+补丁号，必须严格匹配 Go 版本。比如 Go 1.22.x 对应 2024.1.x ，Go 1.21.x 对应 2023.1.x 。 @typescript-eslint 的 6.21.0 必须与 typescript@5.4.5 兼容，查兼容表可知 6.21.x 支持 5.4.x 。 ruff==0.5.4 是最后一个支持 Python 3.8 的版本，如果你的项目还跑在 CentOS 7 上，就必须锁死这个版本。这些不是随便写的数字，而是经过 17 个真实项目验证的黄金组合。

4.2 Go 规则检查： go vet + staticcheck + 自定义 gofumpt 的三级过滤

Go 的检查不能只跑 go vet ，它太基础。必须构建三级流水线：一级用 go vet 捕获语法级错误，二级用 staticcheck 检测逻辑缺陷，三级用 gofumpt 强制格式统一。具体命令：

# 一级：go vet（内置）
go vet -composites=false -printfuncs="Infof,Warningf,Errorf" ./...

# 二级：staticcheck（需提前安装）
staticcheck -checks="all,-ST1005,-SA1019" ./...

# 三级：gofumpt（格式化，非检查但影响规则）
gofumpt -w -extra ./...

参数详解： -composites=false 关闭复合字面量检查，因为 map[string]int{} 这种写法在 Go 1.21+ 是合法的； -printfuncs 指定自定义日志函数，让 go vet 能识别 log.Infof 这类封装； -checks="all,-ST1005,-SA1019" 启用所有检查但排除 ST1005 （错误消息首字母小写）和 SA1019 （已弃用 API），因为前者是风格问题，后者在升级过程中必然存在，应单独处理。 gofumpt -extra 是关键，它比 gofmt 多支持 if err != nil { return err } 的单行折叠，这是 Go 社区事实标准。实操心得： staticcheck 的 SA1019 检查非常耗时，建议在 CI 中只对变更文件运行： git diff --name-only HEAD~1 | grep '\.go$' | xargs staticcheck -checks=SA1019 。我在一个 50 万行的 Go 项目里实测，全量扫描要 47 秒，增量扫描仅 1.2 秒。

4.3 TypeScript 规则检查： tsc --noEmit + eslint + type-check 的三重校验

TypeScript 的检查必须分三步走，缺一不可。第一步 tsc --noEmit 是底线，它只做类型检查，不生成 JS，速度最快。第二步 eslint 是风格和逻辑检查，必须启用 @typescript-eslint/recommended-requiring-type-checking 规则集。第三步 tsc --watch 的类型检查是最终仲裁者，因为 ESLint 的类型信息可能滞后。配置文件 eslintrc.cjs 关键片段：

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: './tsconfig.json', // 必须指定，否则无类型信息
    tsconfigRootDir: __dirname,
  },
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking',
  ],
  rules: {
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'as' }],
    '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: false }], // 允许 void 返回
  },
};

重点： parserOptions.project 必须指向 tsconfig.json ，否则 @typescript-eslint 就是瞎子。 checksVoidReturn: false 是经验之谈——很多 Promise 返回 void 是故意的（比如 sendEmail().catch(console.error) ），强制检查反而干扰开发。CI 流水线命令：

# 第一步：tsc 类型检查（最快）
npx tsc --noEmit --skipLibCheck

# 第二步：ESLint 风格检查（中速）
npx eslint --ext .ts,.tsx src/

# 第三步：tsc 全量检查（最慢，放最后）
npx tsc --skipLibCheck

实测数据：在一个 2 万行 TS 项目的 CI 中，第一步平均 800ms，第二步 2.3s，第三步 4.7s。把最慢的放最后，失败时能快速定位是类型问题还是风格问题。

4.4 Python 规则检查： ruff + mypy + pytest 的轻量级铁三角

Python 的检查要轻快，因为开发者讨厌等待。 ruff 是核心，它用 Rust 编写，比 pylint 快 100 倍。 mypy 做类型验证， pytest 做运行时规则测试。 ruff.toml 配置关键项：

select = ["E", "F", "I", "UP", "RUF"] # 错误、格式、导入、升级、Ruff特有
ignore = ["E501", "F401"] # 忽略行长和未使用导入（由其他工具管）
line-length = 88
target-version = "py311"

E501 （行长）交给 black 格式化， F401 （未使用导入）由 ruff 的 RUF100 替代。 mypy.ini 配置：

[mypy]
plugins = "pydantic.mypy"
disallow_untyped_defs = True
disallow_incomplete_defs = True
warn_return_any = True

disallow_untyped_defs 是铁律，所有函数必须有类型注解。 pytest 规则测试示例：写一个 test_rules.py ，专门验证模块导出规则：

import pytest
from mypackage import __all__ as exported
from mypackage import *

def test_all_exports():
    """验证 __all__ 包含所有公共符号"""
    # 获取模块所有公有属性
    public_attrs = [attr for attr in dir(mypackage) if not attr.startswith('_')]
    # 检查 __all__ 是否覆盖全部
    missing = set(public_attrs) - set(exported)
    assert not missing, f"__all__ 缺少导出: {missing}"

CI 命令：

# Ruff（秒级）
ruff check .

# MyPy（分钟级，但必须）
mypy --show-error-codes .

# Pytest 规则测试（轻量）
pytest test_rules.py -v

实操技巧： mypy 启动慢，用 --cache-dir .mypy_cache 加速； ruff 支持 --fix 自动修复，但 --fix 不会修改 __all__ ，必须人工处理。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 Go 规则常见陷阱： go.sum 哈希冲突与 replace 的隐形炸弹

最常被问的问题：“ go mod verify 报错 checksum mismatch ，但 go mod download 又成功，怎么办？”答案是： go.sum 里记录的哈希值，是模块 zip 包解压后所有 .go 文件内容的 sha256 ，不是 zip 包本身的哈希。所以当你用 go mod edit -replace 替换某个依赖为本地路径时， go.sum 会记录本地路径文件的哈希，而 CI 服务器没有这个路径，自然校验失败。正确做法是： 永远用 go mod edit -replace 后立即 go mod tidy ，然后手动删除 go.sum 中对应模块的哈希行，再 go mod download 重新生成 。我踩过的坑是：某次替换 github.com/some/lib 为本地 ../some-lib ， go.sum 里多了一行 github.com/some/lib v1.0.0 h1:xxx ，但 CI 里 go mod download 会去拉远端包，哈希对不上。解决方案表格：

问题现象	根本原因	修复命令	验证方式
go mod verify checksum mismatch	go.sum 记录了本地路径哈希	go mod edit -dropreplace github.com/some/lib && go mod tidy && go mod download	go mod verify 不报错
staticcheck 报 SA1019 但代码已更新	go.mod 里 require 版本未升级	go get github.com/some/lib@v2.1.0	go list -m github.com/some/lib 显示新版本
go vet 不检查 fmt.Printf 自定义函数	printfuncs 未配置	go vet -printfuncs="Logf,Warnf,Errf"	go vet 对 Logf("msg") 报格式错误

提示： go mod graph 是终极排查工具。当 go list -m all 显示某个模块版本是 v1.2.3 ，但 staticcheck 却在检查 v1.1.0 的 API，运行 go mod graph | grep "some-lib" ，就能看到是谁间接引入了旧版本。

5.2 TypeScript 规则失效场景： node_modules 类型污染与 paths 别名的解析迷宫

最让人抓狂的是：本地 eslint 正常，CI 里却报一堆 @typescript-eslint/no-unused-vars 。根源在于 node_modules 。 @typescript-eslint/parser 的类型信息来自 typescript 包，而 typescript 包里自带 lib.es2020.d.ts 等类型库。如果 CI 的 node_modules 里 typescript 版本是 5.3.3 ，而本地是 5.4.5 ， 5.3.3 的类型库可能缺少 Array.prototype.toReversed() 的定义，导致 eslint 的类型检查失效。解决方案： 在 CI 的 package.json 里锁定 typescript 版本，并用 npm ci 替代 npm install 。 npm ci 会严格按照 package-lock.json 安装，杜绝版本漂移。另一个坑是 tsconfig.json 的 paths 别名。比如配置 "@utils/*": ["src/utils/*"] ， eslint 默认不识别这个别名， import { helper } from '@utils/helper' 会被标红“无法解析模块”。修复方法是在 .eslintrc.cjs 的 settings 里添加：

settings: {
  'import/resolver': {
    typescript: {
      project: './tsconfig.json', // 必须！
      alwaysTryTypes: true,
    },
  },
},

注意： project 字段必须存在，否则 typescript 解析器不会读取 tsconfig.json 的 paths 。这个配置在 12 个项目里救过我的命。

5.3 Python 规则误报难题： mypy 的 Any 泛滥与 ruff 的 F821 误伤

mypy 最常见的误报是“ Any 泛滥”。比如 json.loads(json_str) 返回 Any ，导致后续所有操作都被标红。这不是 bug，是 json 模块的类型存根不完整。官方 typeshed 里 json.loads 的签名是 def loads(s: str, ...) -> Any ，因为 JSON 结构动态，静态分析无法推断。解决方案： 用 typing.cast 显式转换，而非 # type: ignore 。例如：

from typing import cast, Dict, Any
import json

data = cast(Dict[str, Any], json.loads(json_str))  # 明确告诉 mypy：这是 dict
print(data["key"])  # 不再报错

cast 不影响运行时，只是给 mypy 一个类型提示。另一个问题是 ruff 的 F821 （未声明名称）误报。比如在 if TYPE_CHECKING: 块里导入 from __future__ import annotations ， ruff 会认为 TYPE_CHECKING 未定义。修复很简单：在 ruff.toml 里加：

[tool.ruff.pyflakes]
# 启用 TYPE_CHECKING 识别
extend-safe-builtin = ["TYPE_CHECKING"]

实操心得： mypy 的 --show-traceback 参数是神器。当它报错“Cannot determine type of ‘xxx’”，加上 --show-traceback ，就能看到类型推导的完整路径，90% 的疑难杂症靠这个定位。

5.4 跨语言规则协同故障：API 字段名不一致引发的雪崩式失败

这是最痛的教训。Go 后端定义 User struct { UserID int json:"user_id" } ，TS 前端写 interface User { userId: number } ，Python 脚本用 dataclass User: user_id: int 。表面看都合理，但 API 网关一转发， user_id 字段在 TS 里是 undefined ，Python 里是 None ，Go 里是 0 。规则检查工具根本发现不了，因为它们各自检查自己的代码。解决方案： 建立中心化的 OpenAPI Schema 。用 oapi-codegen 从 OpenAPI YAML 生成 Go 代码，用 openapi-typescript-codegen 生成 TS 类型，用 datamodel-code-generator 生成 Python dataclass。所有语言的规则检查，都必须验证其代码是否与 OpenAPI Schema 一致。CI 流水线加入：

# 验证 Go 代码是否匹配 OpenAPI
oapi-codegen -generate types,server -package api openapi.yaml > gen.go
diff gen.go api/user.go || echo "Go 类型与 OpenAPI 不一致！"

# 验证 TS 类型
openapi-typescript-codegen --input openapi.yaml --output src/types
git status --porcelain src/types | grep -q "M" && echo "TS 类型需更新"

这个机制在我们最近一个医疗 SaaS 项目里，拦截了 17 次潜在的字段名不一致，避免了线上数据错乱。规则不是用来限制人的，而是用来对齐认知的——当 Go、TS、Python 都从同一份 OpenAPI 描述生成代码时，“规则”才真正成为团队的共同语言。

6. 规则演进与长期维护：从“检查通过”到“规则即文档”的质变

规则检查的终点，不是绿色的 PASS ，而是让规则本身成为团队知识的载体。我现在的做法是： 把每条规则的检查逻辑，写成可执行的单元测试，并附上失败案例和修复指南 。比如 Go 的 context 规则，不再只是 staticcheck 的一条配置，而是：

// rule_test.go
func TestContextInStruct(t *testing.T) {
    // 失败案例：context 存在 struct 中
    code := `
type Server struct {
    ctx context.Context // 这里应该报错
}
`
    // 检查 staticcheck 是否捕获
    out, _ := exec.Command("staticcheck", "-checks=SA1020", "-f=json").Output()
    // 断言输出包含 "ctx" 和 "Server"
    assert.Contains(t, string(out), "Server")
    assert.Contains(t, string(out), "ctx")
}

TS 的规则同样处理： test-rules.ts 里写一个故意违反 no-explicit-any 的函数，然后用 tsc --noEmit 检查是否报错。Python 的 ruff 规则，用 ruff check --select=RUF100 test_file.py 验证 __all__ 检查。这些测试全部放入 CI，失败即阻断。更进一步，我把所有规则的文档，托管在项目根目录的 RULES.md 里，每条规则包含：

• 规则编号 ： GO-001 、 TS-002 、 PY-003
• 触发条件 ： struct 字段类型为 context.Context 且在包级作用域
• 修复方案 ：改用函数参数传入，或用 context.WithValue 动态注入
• 反例代码 ：贴出真实失败代码片段
• 正例代码 ：贴出修复后代码
• 检查命令 ： staticcheck -checks=SA1020 ./...

这份文档不是静态的 PDF，而是 CI 流水线的一部分——每次 RULES.md 更新，CI 会自动运行对应规则的测试用例，确保文档和代码永远同步。现在新成员入职，第一件事不是看代码，而是读 RULES.md ，因为这里记录的不是“怎么写”，而是“为什么这样写”。比如 GO-003 （禁止 log.Fatal ）的文档里写着：“ log.Fatal 会调用 os.Exit(1) ，绕过 defer 和 runtime.SetFinalizer ，导致资源泄漏。2023 年 Q3，支付网关因此发生 3 次连接池耗尽。”——这才是规则的生命力。规则检查工具会过时，但沉淀下来的“为什么”，会一直指导团队做出正确的技术决策。