· 全部指南
可读 SQL 为何重要
生产日志与 ORM 调试输出常把 SQL 压成数百字符的单行。在 PR 或事故频道里审查极其痛苦：容易漏看缺失的 JOIN 条件、忽略导致索引失效的 OR、直到数据库笛卡尔积爆出百万行才发现问题。可读的 SQL 不是排版爱好，而是安全工具。
sql-formatter 可在本地美化 SELECT、JOIN、CTE 与子查询，不改变语义。关键字对齐、缩进暴露嵌套深度、逗号对齐让 diff 突出逻辑变更而非空白噪声。示例：日志中的 SELECT u.id,u.email,o.total FROM users u JOIN orders o ON u.id=o.user_id WHERE o.created_at>'2024-01-01' AND o.status IN ('paid','shipped') 结构化后 WHERE 子句一目了然。
事故排查推荐流程：从 APM 或 PostgreSQL pg_stat_statements 复制慢查询 → 粘贴 sql-formatter → 识别可疑谓词 → 改写为可用索引列 → 在只读副本验证 → 通过 migration 上线。常见错误：以为格式化能提升性能（不能）；未用 BEGIN/ROLLBACK 就在生产执行格式化后的 ad-hoc 更新；把含客户邮箱或证件号的查询贴进公开工单——即使用本地工具，录屏仍会泄露。
格式化不能替代参数化查询。拼接用户输入仍是 SQL 注入，与字符串多漂亮无关。ORM 应使用绑定参数；DBA 审查原始 SQL 仍要问「值在哪里绑定？」
OpenAPI 文档维护
团队用 OpenAPI（原 Swagger）描述 REST API：路径、操作、请求体、响应 schema 与安全方案，格式为 YAML 或 JSON。规范与实现会悄然漂移——工程师在代码里加了 ?include=metadata 却忘了改 spec，客户端 SDK 生成器就会产出错误类型。
openapi-formatter 整理 YAML/JSON spec，便于 diff 与发布。流程：从仓库复制 spec 片段 → 格式化 → 开 PR 仅展示实质 schema 变更 → 将格式化产物发布到文档站。实现与 spec 不一致时，用 mock-json-generator 或 wiremock-stub-generator 生成示例响应，再写契约测试直到双方对齐。
实例：生产 GET /users/{id} 返回 phoneNumber，spec 仍写 phone。格式化 diff 能抓住重命名；mock 生成器可为移动端 QA 提供 fixture 而无需打生产。OpenAPI 工作可配合 json-formatter 并排检视示例 payload。
联调流程
把格式化嵌入日常开发，而非年度大扫除。SQL：日志采集 → sql-formatter → staging 上 explain → 代码修复 → migration PR。OpenAPI：改 spec → openapi-formatter → CI 中 spectral/openapi lint → 重生客户端 → 部署。
schema 变更应走版本化 migration（Flyway、Liquibase、Alembic），而非从格式化缓冲区手工 ALTER。API 变更按 semver-calculator 规则升版：_additive 响应字段常为 minor；删除或重命名字段为 major。changelog 与 spec 的 deprecated 标记应同步。
跨工具链示例：仓库 YAML 配置 → yaml-converter 转 JSON → openapi-formatter → 与上一发行版产物做 json-diff，捕捉误改 required 数组导致移动端崩溃。
安全
格式化器解析文本，不执行 SQL、不调用线上 API。当查询含 PII——邮箱、证件号、支付 token——这一边界尤为重要。Towalles 在浏览器本地运行，比云粘贴仓减少传输暴露，但 Zoom 共享屏幕或 Jira 附件前仍应脱敏。
建立团队规范：示例用合成 ID；误粘贴真实凭据立即轮换；将格式化输出与源文本同等对待数据分级。SQL 格式化不匿名化数据；OpenAPI 格式化不隐藏 example 字段里的 API 密钥——提交 spec fixture 前用 pii-scanner 扫描。