Scalar SDK 自定义代码实战用三路合并让手写修改在每次重新生成后存活【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar在 Scalar 的 SDK Generator 中生成的客户端代码几乎不可能覆盖你所有的需求你可能想加一个便捷方法、微调一个类型、写个辅助函数或者改改 README。本文讲解 Scalar 的Custom Code自定义代码机制它允许你直接编辑生成出来的代码并在每次重新生成时通过三路合并three-way merge把你的修改携带carry forward下去从而在不 fork 生成器、不丢失后续更新的前提下定制 SDK。读完后你将掌握分支模型、编辑—重建—合并的完整工作流、冲突的产生原因与两种解决方式以及几条避免冲突的实战建议。前提Target 必须关联到 GitHub 仓库自定义代码能力只对你已关联linked到 GitHub 仓库的 target 生效见 Custom Code 文档 与 GitHub Repositories 文档。关联是逐 target 进行的TypeScript 和 Python SDK 可以分别放在不同的仓库里。关联仓库的两种方式通过 Dashboard首次连接时 GitHub 会要求你安装 Scalar GitHub App 并授予它访问所需仓库的权限——Scalar 只需要读写仓库内容和发起 pull request 的权限。随后打开 target在Git settings下选择Organization和Repository点击Connect repository。从今以后每次成功的 build 都会把生成的 SDK 推送到这个仓库。通过 SDK 配置直接设置Dashboard 的关联操作本质上是设置 target 的destinations你也可以在配置文件中直接写出{ targets: { typescript: { destinations: { production: { repo: acme/acme-typescript, branch: main } } } } }属性类型说明repostring生成 SDK 推送到哪个owner/repo。branchstring仓库的默认分支release 会被提升到该分支默认为main。生成物本身固定推到scalar-generated分支。分支模型四个分支各司其职理解自定义代码关键是理解 Scalar 管理的分支模型来自 GitHub Repositories 文档分支职责谁在上面提交scalar-generated保存未经改动的生成器原始输出。Scalar 推到这里你永远不要往这里提交。只有 Scalarscalar-next生成物与你的自定义代码合并后的状态。这是你提交自己修改的地方直接提交或通过 PR也是每次重新生成合并的落点。你和 Scalar默认分支如main只接收已发布状态。Scalar 在scalar-next与默认分支之间保持一个 release pull request其 diff 就是整个待发布内容合并该 PR 才会触发 release 和发布。你合并 release PRscalar-merge-conflict承载一次无法干净合并的重新生成以 pull request 形式交给你解决。Scalar 创建你解决build 永远不会直接提交到你的默认分支整个流程使用仓库中的生成式 workflow 运行全部走默认的GITHUB_TOKEN无需额外配置 token。三路合并是如何工作的每次 build 都会执行一次三路合并比较上一次生成的代码base、本次新生成的代码与你仓库的当前状态你的自定义代码然后把合并结果落到scalar-next分支上。合并完成后按文件分为三种结局未被修改的生成文件干净地更新为最新生成结果你编辑过的生成文件你的修改被保留下来与新生成内容合并你自己新增的文件原样保留不受任何影响。scalar.config.json中对这一能力的官方描述是Customize generated SDKs and keep your changes across regenerations with a three-way mergescalar.config.json。标准工作流编辑 → 重建 → 审查合并第 1 步编辑生成代码。在你的 SDK 仓库里像对待任何普通代码一样修改生成文件、或者新增文件。修改提交到scalar-next集成分支——可以直接推也可以走针对它的 pull request。绝对不要提交到scalar-generated那里保存的是纯净的生成器输出。对于希望被显式钉住的代码段Scalar 还支持自定义代码区域标记见 SDK Generator 总览// scalar-sdk-generator:custom-code retry-helper:start export const withBackoff async T(fn: () PromiseT) { // Anything in here is carried forward on every regeneration. }; // scalar-sdk-generator:custom-code retry-helper:end标记区域内的代码会在每次重新生成时被显式保留下来。第 2 步重建Rebuild。下一次 build 会从最新的 OpenAPI 文档重新生成 SDK并在合并时把你的修改带进scalar-next——你的编辑搭车前进ride along而不是被覆盖。从构建流程看一次 build 会推送到scalar-generated、合并进scalar-next、并更新针对默认分支的 release pull request见 Managing Your SDK。第 3 步审查并合并Review and merge。审查 Scalar 保持打开的 release pull request——它从scalar-next指向你的默认分支标题形如release: X.Y.Z其中包含生成变更、你的自定义代码、changelog 和版本提升。大部分变更会自动合并只有真正的冲突才需要你处理。源码中的三路合并实现三路比较是 Scalar 同步体系的核心原语。在应用端源码中可以看到同一模式的实现check-version-conflict.ts 中的注释明确写道冲突检测是经典三路比较classic three-way comparison——比较原始文档、带本地编辑的工作区文档与新拉取的远端文档并以 registry commit hash 作为缓存键避免重复网络请求配套的 detect-document-conflicts.ts 执行具体的三向比对。此外编辑器侧还实现了通用的三路合并编辑状态机base | local | remote → result见 use-three-way-merge-editor.ts。SDK 代码层的三路合并发生在构建同步链路中但两者的算法思想一致以上次生成态为基准把新生成与人工修改两个方向的变更合并到同一结果里。冲突如何产生以及如何解决冲突的定义当重新生成的文件修改了你恰好编辑过的同一行时就会发生冲突。典型场景你自定义了某个方法而后来该方法在 API 中的签名发生了变化。发生冲突时该 target 的 build 被标记为存在冲突has conflicts这次合并被停放parked在scalar-merge-conflict分支上而不是直接落入scalar-next。你可以用两种方式解决在 Dashboard 中打开 target 的 conflicts 视图对每个冲突文件逐个选择采用生成版本或采用我的版本在 GitHub 中像处理任何普通 Git 合并冲突一样在scalar-merge-conflict的 pull request 上解决冲突。冲突解决后合并结果落到scalar-nextrelease pull request 会随之反映合并后的最终状态之后照常进入审查与发布流程发布机制详见 Publishing 文档。注意仓库侧的分支保护需要在scalar-next和默认分支上允许 Scalar App 与github-actionsbot 推送或干脆不启用保护默认分支只应通过合并 release pull request 前进。实战建议以下是原文档给出的三条经验加上分支纪律的补充能分离就分离自定义代码。位于独立路径下的新文件永远不会冲突所以优先新增一个 helper 文件而不是深入到某个生成文件内部去改。这是降低冲突概率最有效的一招。审查 release pull request。它是生成变更与你的定制化代码唯一交汇的地方也是任何内容 release 或 publish 之前天然的审查点。自定义代码是按仓库per repository隔离的。每个 target 在自己关联的仓库里保存自己的定制化互不影响多语言 SDK 各建各的仓库时各自维护各自的自定义代码。分支纪律是前提。scalar-generated永远只读一切人工提交都进scalar-next只有解决冲突时才会接触scalar-merge-conflict。小结Scalar 的 Custom Code 机制把生成代码和手写代码从二选一变成了可共存三路合并让未触碰的生成文件持续更新、让既有修改被携带、让新增文件不被触碰仅当双方改动同一行时才会产生冲突并且冲突被隔离到scalar-merge-conflict分支支持 Dashboard 逐文件裁决或 GitHub 常规解冲突两种处理方式。配合 关联 GitHub 仓库、构建管理 与 发布流程你可以在完全掌控版本与发布节奏的前提下让 SDK 既跟随 API 演进又保留你团队的手写增强。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
