Sharw's API

简体中文

English

简体中文

English

Appearance

v0.2.0 更新日志 ​

发布日期：2026 年 2 月 26 日

v0.2.0 是 SharwAPI 的第一个重大架构升级版本。此版本对主程序进行了全面重构，引入了插件依赖管理体系，并大幅扩展了 IApiPlugin 插件接口的能力。

升级注意

v0.2.0 包含破坏性变更，直接替换二进制文件后插件可能无法正常运行。请在升级前阅读 迁移指南。

对使用者的变化 ​

日志系统全面升级 ​

原先的日志系统仅在启动阶段输出到控制台，缺乏持久化能力。v0.2.0 引入了 Serilog 作为统一的日志框架：

  • 日志同时输出到控制台和文件
  • 日志文件按天滚动，默认保留最近 30 天，单个文件最大 10 MB
  • 日志文件路径：logs/log-{日期}.txt

受此影响，appsettings.json 中的日志配置节发生了变更。详见 用户侧迁移指南。

插件配置文件独立化 ​

以前所有插件只能读取主程序的 appsettings.json，现在每个插件拥有独立的配置文件：

  • 路径：config/{插件名}.json（位于程序运行目录下）
  • 首次启动时，如果插件提供了默认配置，系统会自动创建该文件

这意味着你可以单独修改某个插件的配置，而不必担心影响其他插件或主程序。

路由前缀可配置 ​

新增 RouteOverride 配置节，支持在不修改插件代码的情况下覆盖插件的路由前缀：

json
{
  "RouteOverride": {
    "my.plugin": "custom-path"
  }
}

例如，将 my.plugin 的路由前缀从默认的 /my.plugin/... 改为 /custom-path/...。

仅对启用了 UseAutoRoutePrefix 的插件生效。

主程序架构重构 ​

主程序从单一的 Program.cs 重构为模块化结构，启动逻辑被拆分到多个专职模块：

模块职责
ApplicationHost应用程序组装与启动
PluginLoader插件发现与加载
PluginDependencyChecker依赖检查与拓扑排序
PluginServiceRegistrar服务注册
EndpointRegistration路由注册
RoutePrefixResolver路由前缀解析

这次重构不影响正常使用，启动方式和配置格式（升级后）保持兼容。

插件隔离加载 ​

插件现在通过独立的程序集加载上下文（AssemblyLoadContext）加载，避免不同插件之间因依赖同一第三方库的不同版本而产生冲突。

升级至 .NET 10 并改为自包含发布 ​

主程序及 sharwapi.Contracts.Core 已从 .NET 9 升级至 .NET 10。同时，主程序发布方式改为自包含（self-contained）：

  • 无需预装 .NET 运行时：.NET 10 运行时已随主程序二进制一同打包，在目标机器上直接运行可执行文件即可
  • 发布包体积增大：相比框架依赖模式，自包含包会包含完整运行时，体积更大
  • 运行时隔离：不受目标机器上已安装的其他 .NET 版本影响

对插件开发者的变化 ​

新增：插件依赖声明（Dependencies） ​

插件现在可以声明它所依赖的其他插件：

csharp
public IReadOnlyDictionary<string, string> Dependencies => new Dictionary<string, string>
{
    { "CorePlugin", "1.0" }   // 1.0 及以上版本（NuGet 间隔表示法）
};

系统在启动时会自动检查依赖是否满足，不满足的插件会被跳过并记录警告日志。支持的版本范围格式与 NuGet 一致（如 1.0、[1.0,2.0)、*）。

新增：自定义依赖验证（ValidateDependency()） ​

除了声明式依赖检查，插件还可以通过实现此方法执行更复杂的运行时依赖判断：

csharp
public bool ValidateDependency(IReadOnlyDictionary<string, string> loadedPluginVersions)
{
    // 自定义逻辑，返回 false 则该插件不会被加载
    return loadedPluginVersions.ContainsKey("RequiredPlugin");
}

默认实现返回 true（不做额外验证）。

新增：自动路由前缀（UseAutoRoutePrefix） ​

启用此属性后，插件的路由会自动添加 /{插件名}/ 前缀：

csharp
public bool UseAutoRoutePrefix => true;

前缀可通过 appsettings.json 的 RouteOverride 节覆盖。

新增：默认配置对象（DefaultConfig） ​

插件可以提供一个默认配置对象，当配置文件不存在时由系统自动生成：

csharp
public object? DefaultConfig => new MyPluginSettings
{
    Port = 8080,
    Enabled = true
};

变更：configuration 参数语义全面调整 ​

这是本次升级最重要的变更之一。

RegisterServices() 和 RegisterRoutes() 的 configuration 参数均改为插件专属配置：

  • v0.1.0：两个方法传入的均为全局 appsettings.json 的配置
  • v0.2.0：两个方法传入的均为插件专属配置文件 config/{插件名}.json 的配置

如果你的插件在这两个方法中读取了 appsettings.json 里的自定义节，需要将该配置移至插件专属配置文件，并通过 DefaultConfig 提供默认值。

详见 开发者侧迁移指南。

变更：目标框架升级至 .NET 10 ​

sharwapi.Contracts.Core 现已面向 net10.0。插件项目需同步将目标框架从 net9.0 更新为 net10.0，否则将无法引用新版本的 Contracts 包。这是本次升级对插件开发者的破坏性变更之一，需要重新编译插件。

详见 开发者侧迁移指南。

变更：改为 NuGet 包引用 ​

sharwapi.Contracts.Core 现已通过私有 NuGet 源分发。插件项目需将对 sharwapi.Contracts.Core 的引用方式从 ProjectReference 改为 PackageReference，并在 nuget.config 中配置私有源。这是本次升级对插件开发者的破坏性变更之一。

详见 开发者侧迁移指南。