docs(golang): add mage cross-platform build guide (#304)

Author: dsx137

docs/blog/golang/architectural/4.md

@@ -3,3 +3,152 @@ title: mage跨平台构建说明
 hide_title: true
 sidebar_position: 4
 ---
+
+# mage跨平台构建说明
+
+在 Go 项目里，“构建”常常被理解成把若干个二进制文件编译出来。但对 OpenIM 这类由多个服务、多个工具、多个部署环境组成的工程来说，只完成编译并不等于完成交付。
+
+真正的问题通常有六个：目标在哪里？要编译到哪些平台？运行时需要多少实例？工具和服务的启动顺序是什么？如何判断进程真的起来了？最终如何把这些产物交给另一台机器使用？
+
+**gomake 的核心价值，是把这些问题收拢到一条以 Mage 为入口、以目录约定为边界、以配置和进程检查为闭环的交付链路里。** 它不是简单地包装 `go build`，而是把“构建、启动、停止、检查、导出”这些动作放进同一套路径、平台和进程模型中，让大型 Go 项目的交付行为可以被重复执行。
+
+## 01. 为什么不能只停留在 go build
+
+单体项目里的构建目标通常很清晰：一个入口，一个产物，一个运行命令。微服务项目则不同。一个仓库里可能同时存在后台服务、同步执行的初始化工具、协议生成任务，以及不同平台下的部署产物。
+
+如果每个服务都靠手写脚本维护，就会很快遇到几个问题：
+
+| 问题 | 表现 |
+| --- | --- |
+| 构建目标分散 | 新增服务后容易忘记同步脚本 |
+| 平台差异外溢 | Unix、Windows 的进程和资源限制逻辑混在一起 |
+| 启动顺序不稳定 | 初始化工具和后台服务没有清晰边界 |
+| 状态判断模糊 | 只看进程名容易误伤或误判 |
+| 产物不可迁移 | 编译出来的文件缺少可执行的启动上下文 |
+
+因此，gomake 没有把重点放在“如何写一条更短的编译命令”上，而是先定义工程交付的几个稳定约定：源码放在哪里、工具放在哪里、输出放在哪里、配置从哪里读、日志写到哪里、当前平台对应哪组产物。
+
+有了这些约定，后面的构建和运行才不会变成散落在仓库各处的脚本片段。
+
+## 02. 用路径模型统一工程坐标
+
+gomake 的第一层抽象是路径模型。
+
+它把项目根目录、配置目录、输出目录、二进制目录、日志目录、归档目录、临时目录、服务源码目录和工具源码目录都纳入同一个路径词汇表。这样一来，构建任务、启动任务、导出任务看到的是同一套坐标，而不是各自拼接路径。
+
+这件事看起来很基础，但在跨平台构建里非常关键。因为产物并不是只有一个目录，而是会按照系统和架构分层，例如当前主机产物、目标平台产物、工具产物、服务产物、导出归档产物。只要路径没有统一，后续每个任务都会重复处理这些差异。
+
+gomake 还允许通过参数覆盖根目录、输出目录、配置目录、服务目录和工具目录。这意味着它既可以服务于标准 OpenIM 仓库布局，也可以被嵌入到相近结构的 Go 项目里。对于 Kubernetes 这类部署环境，配置路径还可以切换到更适合挂载配置的布局，从而避免把本地开发路径硬编码到运行时。
+
+路径模型解决的是一个底层问题：所有任务都必须先知道“同一个工程”指的是什么。只有这个坐标系统稳定，构建和编排才有可能共享状态。
+
+## 03. 目录发现让服务和工具成为约定
+
+gomake 没有要求开发者在脚本里逐个登记所有二进制目标，而是通过目录约定发现它们。
+
+`cmd` 目录代表后台服务，`tools` 目录代表同步工具。只要某个子目录符合 Go 入口的约定，它就会被识别为一个可构建目标。服务和工具会被放进不同的输出区域，也会在启动阶段承担不同角色。
+
+这个区分很重要。
+
+后台服务通常需要常驻运行，需要实例编号、配置路径、进程检查和端口观测；工具则更像启动前的准备动作，例如初始化、迁移或检查。工具执行失败时，后续服务启动应该停止，而不是继续拉起一个依赖条件不满足的系统。
+
+通过目录发现，gomake 把“这个入口是什么类型”从命令参数转移到了工程结构本身。新增服务时，只要放在约定目录里，构建系统就能自动纳入；新增工具时，也会天然进入同步执行链路。这种约定降低了脚本维护成本，也减少了多人协作时遗漏目标的概率。
+
+## 04. 跨平台构建不是循环执行命令
+
+跨平台构建表面上是为不同 `GOOS` 和 `GOARCH` 组合执行编译，实际要处理的问题更多。
+
+gomake 会先确定构建选项：是否启用 CGO，是否按发布模式优化，是否压缩产物，目标平台列表来自显式配置还是当前机器自动识别。随后，它会把服务目标和工具目标分别解析出来，再按平台输出到对应目录。Windows 平台下的可执行文件命名、不同架构下的输出路径、服务与工具的分类都会在同一套模型里完成。
+
+这里有两个设计取舍值得注意。
+
+第一，配置优先级是明确的。代码中传入的构建选项优先于环境变量，环境变量再作为默认输入。这可以避免复杂 CI 或本地环境里的隐式变量意外覆盖上层调用者的决定。
+
+第二，构建并发被主动节制。多平台、多目标同时编译时，如果完全放开并发，很容易把机器 CPU、内存和磁盘 I/O 打满，反而造成构建不稳定。gomake 选择按照机器能力控制并发，让吞吐和稳定性之间保持平衡。
+
+因此，跨平台构建在 gomake 里不是一组循环命令，而是一条可解释的产物生成流水线：先识别目标，再确定平台，再分类输出，最后生成可被启动系统读取的配置基础。
+
+## 05. start-config.yml 把构建结果变成运行计划
+
+构建结束并不代表系统可以运行。gomake 会把已经识别出的服务和工具沉淀到 `start-config.yml` 这类运行配置里，让构建产物进一步变成可执行计划。
+
+这个配置关注三类信息：哪些服务需要常驻运行，哪些工具需要在启动前同步执行，每个服务需要多少实例以及运行时的资源约束。默认情况下，服务会以一个实例开始，最大文件描述符也会有基础默认值；后续使用者可以按部署需要调整。
+
+这一步的意义在于，它把构建系统和运行系统接了起来。
+
+如果没有运行配置，构建脚本只能告诉你“文件已经生成”；有了运行配置，gomake 可以继续回答“应该按什么顺序运行这些文件、应该期待多少进程、应该用什么配置启动”。这也是它区别于普通构建工具的地方：构建产物不是终点，而是启动编排的输入。
+
+## 06. 启动链路先处理确定性，再处理并发
+
+gomake 的启动流程分为两类动作：同步工具和后台服务。
+
+同步工具先执行。它们适合承载那些必须在服务启动前完成的动作，例如准备环境或生成必要数据。只要工具失败，启动流程就会中断。这种“先确定前置条件”的策略，可以避免服务已经拉起但依赖状态不完整的半成功场景。
+
+后台服务随后启动。gomake 会根据配置里的实例数量，为服务注入实例标识和配置路径，并以异步方式启动进程。完整启动时，它还会先清理已经存在的同类服务，等待旧进程退出，再拉起新进程并检查数量是否符合预期。
+
+这里最关键的是进程识别方式。gomake 不是只按进程名判断，而是尽量以可执行文件路径作为匹配依据。对于多服务、多版本或同名二进制并存的机器来说，只看名字很容易误判；按路径匹配则能把“这个进程是不是我刚才构建出来的那个服务”说得更清楚。
+
+启动结束后，gomake 还会检查服务进程数量，并输出相关监听端口。这样用户看到的不只是“命令执行完了”，而是能进一步判断系统是否进入了预期状态。
+
+## 07. stop 和 check 让进程管理形成闭环
+
+如果只有启动，没有停止和检查，服务编排仍然是不完整的。
+
+gomake 的停止逻辑会读取同一份运行配置，定位对应服务进程，先尝试正常终止，再在需要时使用更强制的方式结束进程。停止后还会反复等待和确认，避免命令返回时旧进程仍然残留。
+
+检查逻辑则从另一侧验证系统状态：配置里声明了多少个服务实例，当前机器上是否真的存在对应数量的进程，它们是否暴露了监听端口。这个动作对于本地开发和集成环境都很实用，因为它提供了一个比“看日志猜状态”更直接的入口。
+
+更重要的是，`start`、`stop`、`check` 用的是同一套路径和配置模型。启动时怎么找到服务，停止时也怎么找到；构建时输出到哪里，检查时也从哪里反推。这种闭环减少了状态漂移，让工具链不会因为多个脚本各自维护规则而互相打架。
+
+## 08. 平台差异被隔离在边界上
+
+跨平台工具最容易失控的地方，是把平台差异散落到业务流程里。
+
+gomake 的做法是把差异隔离在边界：Unix 系统需要处理文件描述符限制，Windows 下则没有同样语义；Unix 进程优先级和 Windows 优先级也不是同一种模型；可执行文件后缀、进程控制方式、环境变量行为都可能不同。
+
+这些差异并没有污染到上层的构建和启动叙事里。对于使用者来说，仍然是 `build`、`start`、`stop`、`check` 这些稳定动作；对于实现来说，平台相关能力被拆到对应文件和内部模块里。
+
+这是一种很适合基础设施工具的边界设计：上层暴露稳定语义，下层承认系统差异。跨平台不是假装所有系统一样，而是让差异只出现在必须出现的位置。
+
+## 09. 统一命令执行和日志，让工具可观测
+
+构建和编排工具最终都要大量执行外部命令。如果每个任务都自己处理参数、环境变量、工作目录、标准输入输出、错误输出和优先级，行为很快就会变得不一致。
+
+gomake 把命令执行包装成统一模型：任务只需要描述要执行什么、在哪里执行、带什么环境和输出策略，底层负责把这些行为落实到具体进程。日志也会同时面向控制台和统一文件，控制台输出负责即时反馈，日志文件负责事后排查。
+
+这让 gomake 具备了一个工程工具很重要的特征：失败不是静默的。构建失败、工具失败、服务启动失败、进程检查失败，都能沿着统一的输出和日志模型被定位，而不是分散在不同脚本的临时打印里。
+
+## 10. export 把产物变成可迁移的交付包
+
+很多构建系统到生成二进制文件就结束了，但实际交付还需要回答一个问题：这些文件如何被带到另一台机器上继续使用？
+
+gomake 的 `export` 任务会在构建之后，把服务产物、工具产物、启动配置和编译后的 Mage 启动器放进同一个归档包。这样导出的不只是若干个二进制文件，而是一套带有启动入口和运行计划的交付单元。
+
+这种设计降低了部署侧重新理解项目结构的成本。接收方不需要重新推断哪些文件是服务、哪些文件是工具、应该用什么配置启动；这些信息已经在归档结构中被保留下来。
+
+换句话说，export 让 gomake 的链路从“本地构建”延伸到“可迁移运行”。这对于多平台交付尤其重要，因为不同平台的产物和启动器都需要在打包阶段保持对应关系。
+
+## 11. 协议生成和 bootstrap 是链路的补充
+
+除了核心的构建和服务编排，gomake 还提供了协议生成和首次环境准备能力。
+
+协议生成任务负责围绕 Go 模块和协议目录组织生成流程，让协议文件的更新可以纳入同一个 Mage 入口。bootstrap 脚本则解决第一次使用时的基础问题：确保 Mage 可用，并准备 Go 依赖。
+
+这两个能力不是主链路，但它们体现了同一个设计方向：把重复、容易遗漏、跨环境差异明显的工程动作收进统一入口。用户不需要记住一组互相独立的脚本，而是通过 Mage 任务进入同一套工程语义。
+
+## 12. 总结：gomake 解决的是交付一致性
+
+从源码结构看，gomake 最重要的设计并不是某个单点功能，而是把 Go 项目交付拆成几个稳定层次：
+
+| 层次 | 解决的问题 |
+| --- | --- |
+| 路径模型 | 所有任务共享同一套工程坐标 |
+| 目录发现 | 服务和工具通过结构自动纳入构建 |
+| 平台模型 | 多系统、多架构产物按规则输出 |
+| 运行配置 | 构建结果转化为启动计划 |
+| 进程控制 | 启动、停止、检查形成闭环 |
+| 导出归档 | 本地产物变成可迁移交付包 |
+
+这些层次组合起来，gomake 才从一个构建入口变成一条交付链路。
+
+对于 OpenIM 这样的项目来说，构建工具不能只追求“能编译”，还要保证不同开发者、不同机器、不同平台上的交付动作尽量一致。gomake 的架构价值就在这里：它用约定减少配置，用统一模型隔离平台差异，用运行配置连接构建和进程管理，最终让跨平台构建和服务编排不再是两套割裂的脚本。