跳到主要内容
版本：Next

外部集成

本文档引用的文件

目录​

  1. 引言
  2. HTTP API 集成架构
  3. 类型安全的 RESTful 服务调用
  4. 工程级服务集成
  5. 认证与安全通信配置
  6. 超时与错误处理机制
  7. 集成测试策略
  8. 熔断与弹性设计建议
  9. 典型集成场景
  10. 总结

引言​

本项目通过 IMyPluginNameExternalApi 接口与外部系统进行 HTTP API 集成，并通过 MyPluginNameProjectService 实现工程级服务协调。系统采用 WebApiClientCore 实现类型安全的 RESTful 调用，支持灵活的配置管理、状态同步和异步处理机制。本文档详细说明其集成能力、实现机制和最佳实践。

HTTP API 集成架构​

图示来源

本节来源

类型安全的 RESTful 服务调用​

系统使用 WebApiClientCore 实现类型安全的 HTTP 调用，通过接口定义自动生成客户端代码，避免手动构建请求和解析响应。

接口定义​

IMyPluginNameExternalApi 接口定义了对外部服务的调用契约，使用属性标注 HTTP 方法和路径：

[HttpPost("api/v1/myPluginName/myEntityName")]
Task<MyEntityNameDto> CreateAsync([JsonContent] MyEntityNameCreateDto input);

该设计确保编译时类型检查，减少运行时错误。

依赖注入配置​

在 CMSPluginEntry 中通过 AddHttpApi<T> 注册接口，实现自动注入：

context.Services.AddHttpApi<IMyPluginNameExternalApi>()
    .ConfigureHttpApi(configuration.GetSection(nameof(IMyPluginNameExternalApi)));

配置从 appsettings.json 中读取，支持灵活的环境适配。

本节来源

工程级服务集成​

MyPluginNameProjectService 作为工程级服务，负责协调本地数据与外部系统的状态同步，实现跨系统业务逻辑封装。

服务生命周期管理​

该服务继承自 BaseProjectService，通过重写 StartAsync 和 StopAsync 方法管理生命周期：

  • 启动时：创建变量通道监听器，订阅关键变量变化
  • 停止时：释放资源并可触发后台作业进行清理

变量变更响应机制​

通过 FlowVariableChannelListener 监听特定变量变化，当监控的变量值发生改变时触发事件：

_channelListener.TagChanged += OnTagValueChanged;

事件处理中采用异步任务避免阻塞主线程，确保系统响应性。

外部调用协调​

在变量变化处理中，可协调本地持久化与外部 API 调用：

图示来源

本节来源

认证与安全通信配置​

HTTPS/TLS 配置​

虽然当前配置使用 HTTP，但系统支持 HTTPS 通信。建议在生产环境中使用 HTTPS：

{
  "IMyPluginNameExternalApi": {
    "HttpHost": "https://external-api.example.com/"
  }
}

确保外部服务支持 TLS 1.2+，并在网络层配置证书验证。

认证机制​

系统通过 AuthRequired 属性声明服务需要认证：

public override bool AuthRequired => true;

实际认证逻辑由平台基座处理，通常包括：

  • JWT 令牌验证
  • API Key 校验
  • OAuth2 授权

建议在 IMyPluginNameExternalApi 接口中添加认证头支持：

[Header("Authorization", "Bearer {token}")]

本节来源

超时与错误处理机制​

超时设置​

WebApiClientCore 支持配置请求超时，应在 appsettings.json 中定义：

{
  "IMyPluginNameExternalApi": {
    "HttpHost": "http://127.0.0.1:18000/",
    "Timeout": "00:00:30"
  }
}

或在代码中配置：

services.ConfigureHttpApi(config => {
    config.Timeout = TimeSpan.FromSeconds(30);
});

错误处理​

系统采用分层错误处理策略：

  1. 调用层：捕获异常并记录
  2. 业务层：根据错误类型决定重试或降级
  3. 监控层：记录异常用于告警
private async Task ExecuteExternalApiAsync()
{
    try
    {
        await _serviceProvider.GetRequiredService<IMyPluginNameExternalApi>().CreateAsync(dto);
    }
    catch (Exception e)
    {
        _logger.LogException(e);
    }
}

建议实现重试机制和熔断保护。

本节来源

集成测试策略​

系统提供完整的测试基础设施，支持对集成逻辑进行验证。

测试架构​

  • 单元测试：验证单个方法逻辑
  • 集成测试：验证服务间协作
  • 端到端测试：验证完整业务流程

测试基类​

MyPluginNameApplicationTestBase 提供数据库上下文访问能力，支持在测试中验证数据持久化：

protected virtual void UsingDbContext(Action<CMSPluginDbContext> action)

测试建议​

  1. 模拟外部 API：使用 Moq 或 WireMock 模拟外部服务
  2. 测试异常路径：验证网络超时、服务不可用等情况的处理
  3. 验证状态同步：确保本地数据与外部系统最终一致
  4. 性能测试：评估高并发下的系统表现

本节来源

熔断与弹性设计建议​

虽然当前代码未直接集成 Polly，但建议添加熔断机制以提高系统弹性。

Polly 熔断策略建议​

// 超时 + 重试 + 熔断
Policy
    .Handle<HttpRequestException>()
    .Or<TimeoutException>()
    .CircuitBreakerAsync(
        exceptionsAllowedBeforeBreaking: 3,
        durationOfBreak: TimeSpan.FromSeconds(30)
    );

// 指数退避重试
Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(
        retryCount: 3,
        sleepDurationProvider: retryAttempt => 
            TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))
    );

集成方式​

  1. 装饰器模式：创建包装类实现熔断
  2. AOP 切面：通过拦截器注入弹性逻辑
  3. 服务代理：在 IMyPluginNameExternalApi 调用前添加策略

监控建议​

  • 记录熔断状态变化
  • 设置告警阈值
  • 提供管理接口查看熔断器状态

本节来源

典型集成场景​

与 ERP 系统集成​

应用场景：生产订单变更时同步到 ERP 系统。

与 MES 系统集成​

应用场景：实时同步设备运行数据到 MES。

与其他 CMS 模块集成​

应用场景：跨模块内容协同编辑。

本节来源

总结​

本项目通过 WebApiClientCore 实现了类型安全的外部系统集成，IMyPluginNameExternalApi 提供了清晰的 RESTful 调用接口，MyPluginNameProjectService 封装了复杂的跨系统业务逻辑。系统支持灵活的配置、完善的错误处理和可扩展的集成架构。建议进一步增强熔断机制、完善监控体系，并在生产环境中强制使用 HTTPS 通信，以确保集成的可靠性和安全性。