设计理念

理解 Zongsoft 对公共契约、插件装配、显式元数据和部署组合的设计取舍。

Zongsoft 围绕可插件化的业务应用组织能力。设计的重点是让业务意图、技术实现、运行宿主和交付方式能够分别演进，同时保留清楚的连接契约。

宿主与业务分离

宿主负责启动、配置、服务容器和生命周期。订单处理、消息订阅、报表输出等能力由插件提供。同一个不依赖 Web 请求的业务服务可以被终端命令、后台工作器或 Web 控制器调用。

这种复用有前提：业务契约不能直接绑定到某个宿主的输入输出方式。终端的提示、HTTP 状态码和后台任务的重试策略应留在各自的适配层，而把业务规则放在共享服务中。参见宿主概览。

面向契约选择实现

业务代码通常表达“我要一个缓存”或“我要发布消息”，实现选择由服务注册、提供者及配置完成。这样部署方案可以为不同环境选择不同能力，而不用在业务中散布第三方 SDK 的构造代码。

抽象也有边界。核心类库 保留跨实现共同语义；数据库方言、消息协议、云平台参数留给相应驱动或适配器。一个选项出现在公共接口上，并不说明每个驱动都支持它。调用前应阅读对应实现的限制。

💡 可替换性需要同时满足“接口兼容”和“业务语义兼容”。例如消息发布成功可能只表示已进入客户端队列，不能据此推断消费者已经完成业务处理。

用扩展点连接双方

插件树允许能力拥有者公开稳定的扩展路径，由其它插件贡献对象。提供命令执行器的插件不需要引用所有业务命令，业务命令只需要遵守命令契约和扩展路径约定。

服务容器解决对象依赖，插件树解决贡献与装配，两者各有用途。需要被业务按契约调用的对象适合注册为服务；需要加入某个驱动、命令或过滤器集合的对象适合贡献到扩展点。详见构件与服务。

显式元数据让结构可审查

.plugin 描述装配，.option 描述运行参数，.mapping 描述数据关系，.deploy 描述交付文件。把这些结构从业务调用中提取出来，有助于审查配置、复用方案和定位环境差异。

代价是元数据本身也必须维护。修改程序集名称时要检查清单，修改模型字段时要检查映射，修改部署产物时要检查包内路径。编译通过只覆盖其中一部分契约。

模块表达业务边界

模块拥有服务解析域、事件等应用组织能力，可以优先提供自己的服务，同时复用应用共享服务。模块并不自动隔离数据库、线程和进程权限；需要租户隔离、数据权限或进程隔离时，必须另行设计。

模块名、插件名、服务别名和连接名应有明确命名约定，但不必强制相同。它们承担的职责见基础概念。

部署是应用组成的一部分

应用实际运行的是“宿主发布产物 + 选定插件 + 配置和资源”。维护可重复执行的部署清单，可以减少手工复制遗漏，也让开发、测试和发布使用同一套组合定义。

部署、安装打包和自动升级承担不同阶段的职责，详见部署模型。依赖版本、原生资源与配置覆盖应在交付阶段验证；运行环境发现缺失的插件时不会自动通过 NuGet 补齐。

实践中的取舍

先从一个可运行的最小宿主和一个业务插件开始，再按真实需求引入数据库、消息和外部服务。每增加一个实现，都验证清单加载、服务解析、配置生效和首次调用这条完整路径。这样出现问题时，可以沿着明确的边界定位，而不用把所有依赖一起启动后猜测原因。