> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/overview/conception.md).

# 设计理念

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

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

## 宿主与业务分离

宿主负责启动、配置、服务容器和生命周期。订单处理、消息订阅、报表输出等能力由插件提供。同一个不依赖 Web 请求的业务服务可以被终端命令、后台[工作器](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Components/IWorker.cs)或 Web 控制器调用。

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

## 面向契约选择实现

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

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

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

## 用扩展点连接双方

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

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

## 显式元数据让结构可审查

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

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

## 模块表达业务边界

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

模块名、插件名、服务别名和连接名应有明确命名约定，但不必强制相同。它们承担的职责见[基础概念](/overview/concepts.md#module-service-provider)。

## 部署是应用组成的一部分

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

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

## 实践中的取舍

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/overview/conception.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.