NexusContract.Client 1.0.0-preview.19

NexusContract.Client

BFF/业务层客户端 SDK — 通过 HTTP 调用由 NexusContract Hosting 暴露的 HttpApi。

本包用于消费远程 HttpApi 端点，不用于 HttpApi 内部直接接入 Provider。

📦 安装

dotnet add package NexusContract.Client

🚀 快速开始

单一网关地址（统一代理）

using NexusContract.Client;
using NexusContract.Abstractions.Policies;
using NexusContract.Core.Reflection;

// 预加载契约元数据（与 Hosting/Swagger 保持一致）
NexusContractMetadataRegistry.Instance.Preload(new[] { typeof(TradeCreateRequest).Assembly });

// 统一网关（baseRoute 与 Hosting 的 MapNexusEndpoints 保持一致）
var client = new NexusContractClient(
    new Uri("https://gateway.internal/v3"),
    new SnakeCaseNamingPolicy());

// 执行请求：Client 自动从 OperationId 提取 provider 与路径
var resp = await client.ExecuteAsync(
    new TradeCreateRequest { /* ... */ },
    profileId: "tenant_123");

多 Provider 网关地址（按 Provider 分流）

var client = new NexusContractClient(new Dictionary<string, Uri>
{
    ["alipay"] = new Uri("https://alipay-gateway.internal/v3"),
    ["wechat"] = new Uri("https://wechat-gateway.internal/v3"),
});

var resp = await client.ExecuteAsync(
    new TradeQueryRequest { TradeNo = "202501..." },
    profileId: "tenant_123");

URL 构建规则（与 Hosting 对齐）

Client 根据 OperationId 生成 URL：

{baseUri}/{provider}/{profileId}/{operationTail}

• provider = OperationId 第一段（如 alipay.trade.pay → alipay）
• operationTail = OperationId 其余部分（如 trade/pay）

注意：Hosting 侧需使用 MapNexusEndpoints(baseRoute) 且 baseRoute 与 Client 的 baseUri 保持一致。

✨ 关键特性

• 面向 BFF/业务层：通过 HTTP 调用 HttpApi 端点
• 自描述：URL 自动从契约 OperationId 推导
• 类型推断：响应类型由 IApiRequest<TResponse> 推断
• 统一元数据：与 Hosting/Swagger 共享 NexusContractMetadataRegistry
• 零手动路由：无需手写 URL 或 HTTP 方法

🎯 适用场景

✅ 适用：通过 HttpApi 统一访问多三方 Provider

❌ 不适用：在 HttpApi 内部直接调用 Provider（请使用 Provider 包）

✨ 关键特性

• 面向 BFF/业务层：设计用于通过 HTTP 消费远程 HttpApi 端点
• 自描述：URL 会自动从契约中的 [ApiOperation] 属性中提取
• 类型推断：响应类型由 IApiRequest<TResponse> 接口推断
• 与 DI 集成：与 ASP.NET Core 依赖注入无缝对接
• 零手动路由：无需手动指定 URL 或 HTTP 方法
• 类型安全执行：通过泛型 ExecuteAsync<TResponse> API 提供编译期类型保障
• 最小依赖：仅依赖 NexusContract.Abstractions（用于契约）

🎯 适用场景

✅ 使用场景（何时使用 Client）：

• 构建聚合多个支付服务的 BFF（Backend for Frontend）
• 需要通过 HTTP 调用 HttpApi 端点的业务服务
• 与集中式三方网关 API 通信的微服务

❌ 不适用场景（何时不使用 Client）：

• 在 HttpApi 内部（请直接使用 FastEndpoints + Provider）
• 在没有 HttpApi 层的情况下直接集成 Provider（请使用 Provider 包）
• 同一进程内的服务器间通信（请直接使用 Provider）

🏗️ 架构

┌─────────────────────────────────────┐
│   BFF / 业务层                           │
│   （你的 ASP.NET Core API）             │
└─────────────────────────────────────┘
         ↓ 使用（HTTP）
┌─────────────────────────────────────┐
│   NexusContractClient（SDK）           │  ← 本包
├─────────────────────────────────────┤
│  - HTTP 通信层                         │
│  - 请求/响应 序列化                    │
│  - 自动 URL 提取                       │
│  - 类型安全 API（ExecuteAsync）        │
└─────────────────────────────────────┘
         ↓ 使用 HTTP 调用到
┌─────────────────────────────────────┐
│   HttpApi（示例：Demo.Alipay.HttpApi）  │
│   （Hosting + Provider）               │
└─────────────────────────────────────┘
         ↓ 调用
┌─────────────────────────────────────┐
│   Provider（AlipayProvider）           │
│   （直接 OpenAPI 集成）               │
└─────────────────────────────────────┘

📚 相关包

• NexusContract.Abstractions - 核心契约与属性
• NexusContract.Core - 网关引擎与执行管道
• NexusContract.Providers.Alipay - 支付宝 Provider 实现

📖 文档

• GitHub 仓库
• 宪法框架
• 客户端 SDK 指南

🎯 目标框架

• 要求：.NET 10（预览）
• 兼容性：支持任意 .NET 10+ 应用程序

📄 许可证

MIT 许可证 - 详见 LICENSE