juicer – 从现有代码中榨取SSOT Image: AI generated

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

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

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

所以做了juicer。从现有代码中榨取SSOT。

整个水果放进去，果汁出来

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

juicer scan --openapi ./my-project

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

零运行时开销。无需插桩。纯静态分析。学术上同方向也得到了验证。Huang et al.（2024）在ICSE上发表了Respector，仅通过源码静态分析就能自动生成REST API的OpenAPI规范。

三个框架

框架语言提取内容
GinGo路由、绑定、响应、中间件
NestJSTypeScript装饰器、DTO、守卫、拦截器
FastAPIPython路由、Pydantic模型、依赖

Go、TypeScript、Python——覆盖最常用的三个后端框架。

提取内容

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

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

DDL整合

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

juicer ddl ./migrations -o ./schema

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

sqlc查询脚手架

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

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

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

juicer sql status

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

进入yongol管道

juicer的输出是yongol的输入。

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

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

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

开始

npx skills add park-jun-woo/juicer

juicer scan --openapi ./my-project

现有代码变成果汁。

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

参考文献

  • 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

相关文章