Healnet.Core 4.0.15

Healnet.Core 核心契约层

版本: v4.0.14 | TFM: net10.0 | 依赖: Healnet.Common | NuGet: Healnet.Core 4.0.14

概述

Healnet.Core 是 Healnet 微服务框架的核心契约层，提供领域驱动设计（DDD）基础设施、统一异常体系、仓储/缓存/日志抽象、API 响应格式、微服务通用能力抽象，以及 AI 能力的抽象契约。它只定义抽象契约与 POCO，不携带任何具体技术 SDK 依赖——这是"依赖倒置（DIP）"的关键：上层 Infrastructure 实现这些契约，而契约本身保持稳定、可被任意宿主复用。

⭐ AI 能力已彻底 DIP：所有 AI 抽象接口、选项 POCO、上下文模型、记忆契约/实体已上移至本层（Healnet.Core.AI / Healnet.Core.AI.Memory）。Core 的 csproj 不引用 Microsoft.Extensions.AI / Semantic Kernel / Agent Framework——这些契约是纯接口 + POCO，与具体 AI 框架完全解耦。具体实现（如 UnifiedAIService）在 Healnet.Infrastructure.AI。

⚠️ 重要说明：

1. Core 不提供 AddCore() 之类的 DI 注册方法。它仅包含契约与抽象；具体注册在 Healnet.Infrastructure 或宿主项目完成。
2. Core 不含 MediatR / CQRS（ICommand/IQuery/IMediator 并非库 API，仅旧文档示例残留）。
3. 旧文档出现的 Enumeration、Filtering 类型不存在于源码。
4. 关于 ReleaseNotes 的模块归属：Core 的 PackageReleaseNotes 在 3.0.1 条目中提及“新增 ApiKeyAuthenticationHandler”与“新增 GrpcClientBase 泛型基类”，但经核对源码，这两个类型实际位于 Healnet.Infrastructure（Infrastructure.Authentication.ApiKeyAuthenticationHandler 与 Infrastructure.gRPC.GrpcClientBase），属于实现层而非 Core 类型。Core 仅定义认证抽象（ITokenService/JwtOptions）与 Consul 抽象（IConsulService/ConsulOptions）。下方版本历史忠实引用 csproj ReleaseNotes 的变更描述，请以类型实际所在程序集为准。

核心特性

• ✅ DDD 实体 - Entity<TKey> / AggregateRoot<TKey> / ValueObject / AuditableEntity / SoftDeleteEntity / DomainEvent
• ✅ 统一异常 - 7 种 HTTP 业务异常 + 协议异常（带固定 ErrorCode）
• ✅ 仓储模式 - IRepository<T,TKey> / IReadOnlyRepository<T,TKey> 泛型接口
• ✅ 工作单元 - IUnitOfWork（事务抽象）
• ✅ 服务基类 - BaseService / CrudService<TEntity,TRequest,TResponse,TKey>
• ✅ API 响应 - ApiResponse / ApiResponse<T> / PagedResponse<T>
• ✅ 消息队列抽象 - IMessagePublisher / IMessageSubscriber
• ✅ 缓存/日志抽象 - ICacheService / ILoggerService
• ✅ 微服务抽象 - 认证（ITokenService）、服务发现（IConsulService/IConsulHttpClient）、HTTP（IHttpClientService）、幂等、功能开关、请求上下文、发件箱、API 版本
• ✅ AI 契约 ⭐ - IAIService / IAgentService / ICopilotClient / IAgentContextManager / IChatContextManager / IRAGService + Memory 三契约

核心组件

1. 实体与值对象 (Entities) — 命名空间 Healnet.Core.Entities

2. 异常体系 (Exceptions) — 命名空间 Healnet.Core.Exceptions

基类 HealnetException : Exception，含 int ErrorCode、string UserMessage、bool IsRetryable。

协议异常（带固定 ErrorCode，部分可重试）：SqlInjectionException(4001)、PermissionDeniedException(4031)、ResourceNotFoundException(4041)、ValidationFailedException(4002)、DatabaseException(5001,可重试)、LLMException(5002,可重试)、TimeoutExceptionEx(5041,可重试)、RateLimitedException(4291,可重试)。

3. 接口抽象 (Interfaces) — 命名空间 Healnet.Core.Interfaces

4. AI 契约 ⭐ — 命名空间 Healnet.Core.AI

纯接口 + POCO，不引用任何 AI SDK。

接口：

选项 / 枚举（POCO）：

• AIOptions：Provider(AIProvider)、Framework(AIFramework，⚠️ 只写不读的占位枚举)、ApiKey、Endpoint、ModelName("gpt-4o")、MaxTokens(4096)⚠️、Temperature(0.7)⚠️、TopP(0.9)⚠️、ContextWindowSize(8192)⚠️（⚠️ 四项 4.0.15 起标 [Obsolete]：未被任何实现接线，配置不生效）、HttpClientTimeoutSeconds(90，已接线)、RAG(RAGOptions)、AgentFramework(AgentFrameworkOptions，⚠️ 占位配置零读取)
• enum AIProvider { SemanticKernel, MicrosoftAI, Custom }
• enum AIFramework { SemanticKernel, AgentFramework, Hybrid }（⚠️ 占位，5.0 删除）
• RAGOptions：Enabled(true)、TopK(5)、MaxContextLength(3000)
• AgentFrameworkOptions：Endpoint、DeploymentName("gpt-4o")、EnableToolCalling(true)、MaxIterations(10)、Dictionary<string,string> Tools

上下文模型（POCO，框架无关）：

• AgentContext：ContextId/AgentName/List<AgentMessage> Messages/AddUserMessage/AddAssistantMessage/ClearHistory
• AgentMessage：Role/Content/Timestamp/Metadata
• ChatContext：仅含 List<ChatMessage> Messages（不依赖 Semantic Kernel 的 ChatHistory）、AddUserMessage/AddAssistantMessage/ClearHistory
• ChatMessage：Role/Content/Timestamp
• Document：Id/Content/Metadata/Score

5. AI 记忆契约 ⭐ — 命名空间 Healnet.Core.AI.Memory

Contracts（接口 + 配置/记录 POCO）：

Entities（纯 POCO，无 ORM 特性；映射在 Infrastructure 的 SqlSugar Fluent）：

• ConversationSession：Id/SessionId/UserId/Domain?/DatabaseName?/Title?/Status(1=active)/CreatedAt/UpdatedAt
• ConversationTurn：Id/SessionId/TurnNo/UserId/Domain?/DatabaseName?/UserQuery?/Response?/IsValid/RowCount/ErrorMessage?/TokensUsed/DurationMs/Status(1)/CreatedAt

6. 服务基类 (Services) — 命名空间 Healnet.Core.Services

7. API 响应 (Responses) — 命名空间 Healnet.Core.Responses

8. 其他模块

| 模块 | 命名空间 | 说明 | |------|----------|------| | 全局异常中间件 | Core.Middleware | ExceptionHandlerMiddleware（捕获异常→ApiResponse，映射 400/401/403/404/422/500）。4.0.11 增强：补 HealnetException 基类分支（原 SqlInjection/PermissionDenied/ResourceNotFound/ValidationFailed/Database/LLM/Timeout/RateLimited 等协议子类全部落入兜底 500）；ErrorCode → HTTP StatusCode 统一映射——100-599 原值直通、4031→403、4041→404、4291→429、其余 4xxx→400、5xxx→500、未知区间→500，消除 4031 等非法状态码直通 HTTP 的问题；app.UseExceptionHandlerMiddleware() | | 幂等性 | Core.Filters | [Idempotent] 特性（TtlSeconds=3600、HeaderName="Idempotency-Key"）+ IIdempotencyStore | | API 版本 | Core.Versioning | [ApiVersion] 特性 + ApiVersionConstants（RouteTemplate/DefaultVersion="1.0"/VersionHeader="X-Api-Version"） | | 发件箱 | Core.Outbox | OutboxMessage（OutboxMessageStatus 枚举：Pending/Delivered/DeadLetter）+ IOutboxStore| | 功能开关 |Core.Features|IFeatureFlagService（IsEnabledAsync/GetValueAsync<T>/GetEnabledFeaturesAsync）+ FeatureContext| | 请求上下文 |Core.Context|IRequestContext（TraceId/TenantId/UserId/UserName/ClientIp/UserAgent）+ DefaultRequestContext（AsyncLocal） | | 认证抽象 | Core.Authentication|ITokenService+JwtOptions（实现在 Infrastructure.Authentication） | | 服务发现抽象 | Core.Consul|IConsulService+IConsulHttpClient+ConsulOptions（实现在 Infrastructure.Consul；ConsulOptions支持唯一实例 ID 注册、gRPC 健康检查，以及 **4.0.10 新增**GrpcLegacyTagFallback(默认 false) / GrpcLegacyFallbackTag(默认 server)，用于遗留 gRPC 实例发现回退） | | HTTP 抽象 | Core.Http|IHttpClientService+IHttpClientFactoryService+IHttpInterceptor（实现在 Infrastructure.Http） | | Skill | Core.Skill|ISkillLoader+SkillOptions（SkillStorageMode：Local/Oss）+ OssOptions` |

依赖关系

graph LR
    A[Healnet.Core] --> B[Healnet.Common]
    A --> C[Microsoft.Extensions.Logging.Abstractions]
    A --> D[Microsoft.AspNetCore.Http.Abstractions]
    A --> E[Microsoft.Extensions.Primitives]

⚠️ 注意：Core 仅依赖上述 3 个轻量 NuGet 包 + Common。无 Semantic Kernel / Microsoft.Extensions.AI / MediatR / SqlSugar / EF Core 等任何重量级依赖。

使用指南

1. 创建实体

using Healnet.Core.Entities;

public class User : Entity<long>
{
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
}

public class Product : AuditableEntity
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

public class Article : SoftDeleteEntity
{
    public string Title { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
}

2. 统一异常处理

using Healnet.Core.Exceptions;

throw new BusinessException("库存不足");                       // → 400
throw new NotFoundException($"用户 {userId} 不存在");          // → 404
throw new ValidationException(new List<string> { "邮箱格式不正确" });  // → 422
throw new ForbiddenException("无权访问此资源");                 // → 403

3. API 响应格式

using Healnet.Core.Responses;

// 成功响应（Data 泛型，Timestamp 构造时自动填充）
return ApiResponse<User>.Success(user, "查询成功");
return ApiResponse<List<User>>.Success(userList);

// 失败响应（工厂方法对应各 HTTP 语义）
return ApiResponse.Fail("操作失败");                  // code=500
return ApiResponse.BadRequest("参数错误");            // code=400
return ApiResponse.Unauthorized();                    // code=401
return ApiResponse.Forbidden();                       // code=403
return ApiResponse.NotFound("用户不存在");            // code=404

// 泛型版本（含可指定状态码的 SuccessResult）
var created = ApiResponse<User>.SuccessResult(user, 201);   // code=201
var failed  = ApiResponse<string>.Fail("boom");             // code=500, Data=null

// 分页响应
var paged = PagedResponse<User>.Create(users, page, pageSize, totalCount);

⚠️ IsSuccess 严格等于 Code == 200：SuccessResult(data, 201) 的 IsSuccess 为 false。 调用方以 IsSuccess 判断成功时，非 200 状态码（含 201/204）都会得到 false——按 Code 判断更稳妥。

文档可见性（4.0.13 起）

Core 4.0.13 起 csproj 开启 GenerateDocumentationFile，包内随附 lib/net10.0/Healnet.Core.xml。原因：SwaggerOptions.IncludeXmlComments 默认 true 但只在输出目录里找 *.xml——Core 此前不产 XML，ApiResponse 的契约注释写了也进不了 swagger schema，外部调用方看到的 code 只是无描述的 integer，于是把业务码误当成 HTTP 状态码来读。

服务端拿到这个文件的方式见 examples/ 模板 csproj：PackageReference ... GeneratePathProperty="true" + 构建/发布两个 Target 从包目录定向复制。不要改用 CopyDocumentationFilesFromPackages——它会把 100+ 个三方包文档一并复制（实测 109 个 / 46MB），且 Swashbuckle 每次生成文档都会重扫这些文件。

4. 仓储接口

using Healnet.Core.Interfaces;

public interface IUserRepository : IRepository<User, long>
{
    Task<User?> GetByEmailAsync(string email);
    Task<IEnumerable<User>> GetActiveUsersAsync();
}

5. 服务基类

using Healnet.Core.Services;
using Healnet.Core.Interfaces;

public class UserService : BaseService, IUserService
{
    private readonly IRepository<User, long> _repository;
    public UserService(ILoggerService logger, IRepository<User, long> repository) : base(logger)
        => _repository = repository;

    public async Task<User> GetByIdAsync(long id)
    {
        ValidateId(id);
        var user = await _repository.GetByIdAsync(id);
        if (user is null) throw new NotFoundException($"用户 {id} 不存在");
        return user;
    }
}

6. 全局异常处理中间件

// Program.cs — 推荐用 Core 版（功能最全，支持 Path/Timestamp）
app.UseExceptionHandlerMiddleware();

7. 使用 AI 契约（消费方视角）

using Healnet.Core.AI;

public class ChatController
{
    private readonly ICopilotClient _copilot;
    public ChatController(ICopilotClient copilot) => _copilot = copilot;

    public async Task<string> Ask(string prompt)
        => await _copilot.ChatAsync(prompt);   // 实现由 Infrastructure.AI 注入
}

NuGet 包信息

版本历史

以下变更说明整理自 Healnet.Core.csproj 的 PackageReleaseNotes，具体日期以各发布记录为准（本文不杜撰日期）。

许可证

MIT License