codistill -- 从现有代码中蒸馏SSOT

codistill – 从现有代码中蒸馏SSOT Image: AI generated

如果你想在现有项目中采用SSOT但无法从头重写，如果你想从遗留的Go、TypeScript、Python、Java、C#、Rust或PHP后端中自动提取OpenAPI和DDL——codistill从现有代码中蒸馏规范。

“我们已经有200个端点了”

有人读了yongol的文章问：“好是好，但我们项目已经有几万行代码了。需要从头写SSOT吗？”

从头写当然好，但现实中不可能。没有哪个团队能停下运行中的服务从零写规范。不能拆正在营业的店的地基。

所以做了codistill。从现有代码中蒸馏SSOT。

代码放进去，规范出来

codistill对Web框架源码进行静态分析，自动提取声明式规范。

codist scan --openapi ./my-project

这一行就能从现有代码生成OpenAPI 3.0规范。手动要花几天的事，秒级完成。

如果项目已经带有openapi.yaml，codist会检测并合并它——结构来自代码（路由注册才是事实的基准），描述来自现有规范，而那些不再连接到任何路由的死规范会被丢弃。

零运行时开销。无需插桩。纯静态分析。学术上同方向也得到了验证。Huang et al.（2024）在ICSE上发表了Respector，仅通过源码静态分析就能自动生成REST API的OpenAPI规范。codistill自身也针对大型真实代码库——Immich、Ghost、NocoDB、Plane、AppFlowy等——经过了锤炼，修复了只有在生产级源码上才会暴露的提取缺陷（changelog）。

十六个框架，八种语言

语言	框架
Go	Gin, Fiber, Echo
TypeScript	NestJS, Fastify, Hono, Express
Python	FastAPI, Flask, Django
Java	Spring Boot, Quarkus
C#	ASP.NET Core
Rust	Actix Web
PHP	Laravel
Deno TypeScript	Supabase Edge Functions

最初的三个框架——Gin、NestJS、FastAPI——如今已覆盖八种语言、十六个框架。框架会从go.mod、package.json、requirements.txt、pom.xml、*.csproj、Cargo.toml、composer.json或supabase/functions/自动检测，也可以用--framework指定。大多数后端通过tree-sitter解析；Go+Gin则直接使用go/ast + go/types。

提取内容

层	输出
路由	HTTP方法、路径、处理器位置、中间件
请求	Body绑定类型+结构体字段、查询/表单/路径参数、文件上传
响应	状态码、Body类型+结构体字段、`json`/`validate`标签
OpenAPI	paths、parameters、requestBody、responses、components/schemas
DDL	从迁移历史中按表生成CREATE TABLE快照（ALTER COLUMN、约束、索引）
SQL	Repository方法骨架——CRUD类型、表、参数、返回值

散布在源码中的决策被浓缩为声明式规范。

DDL整合

迁移文件堆了50个，很难看出当前Schema是什么状态。得在脑子里重放累积的ALTER TABLE顺序。

codist ddl ./migrations -o ./schema

读取整个迁移历史，每个表输出一个干净的CREATE TABLE快照。50个文件变成表数量的.sql文件。

它处理CREATE/ALTER/DROP TABLE、ADD/DROP/ALTER COLUMN、约束和索引。对于基于Prisma的项目，codist prisma直接读取schema.prisma——包括复合FK、enum和pgvector类型——并生成按FK顺序排列、可干净地应用到运行中数据库的DDL。

sqlc查询脚手架

从Repository模式代码中提取SQL查询骨架。

codist sql next --repo ./repository --queries ./db/query

next——棘轮工作流。显示下一个没有查询的Repository方法，写骨架，继续下一个。全部填完就停。

codist sql status

显示当前进度。不是代理宣布"我做完了"，而是机器判定剩余方法数。

进入yongol管道

codistill的输出是yongol的输入。

现有代码
  ↓ codist scan --openapi
  ↓ codist ddl
  ↓ codist sql next
OpenAPI + DDL + sqlc查询
  ↓ yongol validate
  ↓ yongol generate
SSOT驱动的代码库

codistill从现有代码反向提取SSOT，yongol验证一致性并生成代码。从brownfield到greenfield的转换不是一次性的，而是渐进的。Perry和Wolf（1992）定义了架构侵蚀（erosion）和漂移（drift）——违反规范是侵蚀，对规范麻木是漂移。codistill是从已经发生漂移的代码中反向提取规范的工具。

不是基础施工而是抗震加固。Martin Fowler（2004）的Strangler Fig模式——不一次性替换遗留系统，渐进式地包裹。不关门就加固建筑。

开始

npx skills add park-jun-woo/codistill

codist scan --openapi ./my-project

现有代码被蒸馏为规范。

代码：github.com/park-jun-woo/codistill

yongol——AI编码SaaS的龙骨 — codistill提取的SSOT的验证和代码生成工具。
Ratchet Pattern——让代理走到终点的方法 — codist sql next棘轮工作流的背景。
Reins Engineering——有缰绳的AI — codistill所属的工程体系。

参考文献

Huang, R., Motwani, M., Martinez, I., & Orso, A. (2024). Generating REST API Specifications through Static Analysis. Proceedings of the IEEE/ACM 46th International Conference on Software Engineering (ICSE 2024). ACM
Lercher, A., Macho, C., Bauer, C., & Pinzger, M. (2024). Generating Accurate OpenAPI Descriptions from Java Source Code. arXiv:2410.23873. arXiv
Chauhan, S., Rasheed, Z., et al. (2026). OpenAI for OpenAPI: Automated generation of REST API specification via LLMs. Journal of Systems and Software. arXiv
Perry, D. E. & Wolf, A. L. (1992). Foundations for the Study of Software Architecture. ACM SIGSOFT Software Engineering Notes, 17(4), 40-52. ACM
De Silva, L. & Balasubramaniam, D. (2012). Controlling software architecture erosion: A survey. Journal of Systems and Software, 85(1), 132-151. ScienceDirect
Fowler, M. (2004). StranglerFigApplication. martinfowler.com/bliki. Link
Fritzsch, J., Bogner, J., Wagner, S., & Zimmermann, A. (2019). Microservices Migration in Industry: Intentions, Strategies, and Challenges. 2019 IEEE ICSME, pp. 481-490. arXiv
Curino, C. A., Moon, H. J., & Zaniolo, C. (2008). Graceful database schema evolution: the PRISM workbench. Proceedings of the VLDB Endowment, 1(1), 761-772. VLDB
Nghiem, D., Guo, H., & Foster, J. S. (2023). A Qualitative Study of REST API Design and Specification Practices. 2023 IEEE VL/HCC, pp. 148-156. IEEE