# NewLife.Core 架构设计 > 版本：v11.17 | 日期：2026-07-15 | 从代码结构逆向整理 本文档描述 NewLife.Core 核心库的架构设计。需求定义见[需求文档](/NewLife/X/Blob/dev/Doc/需求文档.md)，功能追踪见[功能清单](/NewLife/X/Blob/dev/Doc/功能清单.md)。 ## 1. 项目分层 NewLife.Core 采用**单项目 + 目录命名空间**的轻量分层架构，不拆分多项目（符合 NewLife 从两层起步的理念）。 ``` NewLife.Core/ ├── Common/ # 根命名空间 NewLife.*（基础类型） ├── Extension/ # NewLife.* 扩展方法 ├── Event/ # NewLife.* 事件与弱引用委托 ├── Exceptions/ # NewLife.* 异常类型 ├── Stub/ # 兼容性填充（低版本 .NET 缺失类型） ├── Collections/ # NewLife.Collections 集合与池化 ├── Caching/ # NewLife.Caching 缓存系统 ├── Configuration/ # NewLife.Configuration 配置系统 ├── Data/ # NewLife.Data 数据结构 ├── Log/ # NewLife.Log 日志与追踪 ├── Model/ # NewLife.Model 应用框架 ├── Reflection/ # NewLife.Reflection 反射扩展 ├── Net/ # NewLife.Net 网络库 │ └── Handlers/ # 编解码器 ├── Http/ # NewLife.Http HTTP 组件 ├── Remoting/ # NewLife.Remoting RPC 框架 ├── Serialization/ # NewLife.Serialization 序列化 │ ├── Json/ # JSON 序列化子模块 │ └── Xml/ # XML 序列化子模块 ├── Security/ # NewLife.Security 安全加密 ├── Threading/ # NewLife.Threading 定时调度 ├── Messaging/ # NewLife.Messaging 消息与事件 ├── Web/ # NewLife.Web Web 工具 ├── IO/ # NewLife.IO 文件与存储 ├── Compression/ # NewLife.Compression 压缩归档 ├── Algorithms/ # NewLife.Algorithms 数据算法 ├── Buffers/ # NewLife.Buffers 高性能缓冲区 ├── Xml/ # NewLife.Xml XML 配置 ├── Windows/ # NewLife.Windows Windows 特定 ├── Setting.cs # 核心配置 Setting └── NewLife.Core.csproj # 多目标框架：net45~net10.0 ``` ## 2. 模块架构 ### 2.1 基础扩展（M1） 层内无依赖，被所有上层模块依赖。 核心组件：`Utility`（类型转换）、`StringHelper`（字符串）、`DisposeBase`（资源释放）、`Runtime`（运行时）、`TimeProvider`（时间抽象）、`IDictionarySource`（字典数据源）、`MachineInfo`（机器信息）。 ### 2.2 日志与追踪（M2） ``` ILog (接口) ├── TextFileLog # 文件日志 ├── ConsoleLog # 控制台日志 ├── NetworkLog # 网络日志（UDP） ├── CompositeLog # 组合日志 ├── LevelLog # 级别过滤包装 └── ActionLog # 回调日志 ITracer (接口) └── DefaultTracer # 集成星尘平台 APM XTrace # 全局静态日志入口 Logger # 日志工厂 PerfCounter # 性能计数器 LogEventListener # ETW 日志监听 ``` ### 2.3 定时调度（M3） ``` TimerX # 高精度定时器（支持 Cron 和异步回调） Cron # Cron 表达式解析（秒级 7 域） TimerScheduler # 定时任务调度器 ThreadPoolX # 线程池扩展包装器 ``` ### 2.4 序列化（M4） ``` IFormatterX (接口) ├── Json # JSON 序列化 │ ├── JsonParser │ ├── JsonReader │ └── JsonWriter ├── Binary # 二进制序列化 ├── Xml # XML 序列化 │ ├── XmlParser │ └── XmlComposite └── SpanSerializer # Span 零分配序列化 CsvFile / CsvDb<T> # CSV 读写 ExcelReader / ExcelWriter # Excel 读写 SpanReader / SpanWriter / SpanHelper # 缓冲区工具（NewLife.Buffers） PooledByteBufferWriter # 池化缓冲写入器 SerialHelper # 序列化辅助 SafeInt64Converter / LocalTimeConverter # 类型转换器 ``` ### 2.5 配置系统（M5） ``` IConfigProvider (接口) ├── FileConfigProvider │ ├── JsonConfigProvider (默认) │ ├── XmlConfigProvider │ └── IniConfigProvider ├── HttpConfigProvider # 远程配置（星尘） ├── ApolloConfigProvider # Apollo 配置中心 └── CompositeConfigProvider Config<T> # 泛型配置基类（单例） SysConfig # 系统配置（继承 Config<T>） ConfigHelper # 配置辅助 CommandParser # 命令行解析 ``` ### 2.6 安全加密（M6） ``` SecurityHelper # RSA/AES/DES/MD5/SHA/CRC 统一方法集 RSAHelper # RSA 非对称加密 DSAHelper # DSA 数字签名 SM4 # 国密对称加密 RC4 # 流加密算法 Crc16 / Crc32 # CRC 循环冗余校验 Murmur128 # MurmurHash3 128 位哈希 IPasswordProvider # 密码哈希与验证接口 Rand # 安全随机数生成 PKCS7PaddingTransform # PKCS7 填充/去填充算法 Asn1 / Asn1Tags # ASN.1 数据格式编解码 ``` ### 2.7 应用框架（M7） ``` ObjectContainer # IoC/DI 容器（兼容 IServiceProvider） Host # 后台服务托管（Windows 服务 + Linux Systemd） IPlugin / PluginManager # 插件框架 Actor # Actor 并发模型 IPipeline / Pipeline # 双向处理链 DeferredQueue # 延迟批处理队列 IMessage # 请求-响应消息接口 IEventBus / EventBus # 事件总线 EventHub<T> # 主题路由事件中心 ``` ### 2.8 缓存系统（M8） ``` ICache (接口) ├── MemoryCache # 内存缓存（含 MemoryQueue<T>） └── Redis # ⚠️ 已提取到 NewLife.Redis ICacheProvider # 缓存提供者 Cache / CacheLock # 缓存基类 / 分布式锁 IProducerConsumer<T> # 生产者消费者接口 QueueEventBus<T> # 消息队列事件总线 Pool<T> / ObjectPool<T> # 对象池（NewLife.Collections） ``` ### 2.9 数据与算法（M9） ``` IModel # 模型数据接口（字符串键索引） IExtend # 扩展数据接口（扩展属性字典） IFilter / FilterContext # 数据过滤器（责任链） IPacket (接口，零拷贝数据包) ├── Packet # [Obsolete] 原始实现 ├── ArrayPacket # byte[] 包装 └── OwnerPacket # 内存持有者包装 IPacketEncoder / DefaultPacketEncoder # 数据包编码器 RingBuffer # 环形缓冲区（协议组包） Snowflake # 雪花 ID（分布式唯一 ID） GeoHash / GeoPoint # 经纬度哈希 DbTable / DbRow # 内存数据表 IInterpolation / ISampling / AlignModes # 采样插值框架抽象 AverageSampling # 降采样 LinearInterpolation # 线性插值 IData # 网络数据帧抽象 ``` ### 2.10 网络通信（M10） ``` NetServer # 网络服务器基类 ├── TcpServer # TCP 服务器 └── UdpServer # UDP 服务器 NetClient # 统一 TCP/UDP 客户端 NetSession # 高级网络会话 INetHandler (管道接口) ├── StandardCodec # 请求-响应编解码 ├── LengthFieldCodec # 长度字段粘包拆包 ├── SplitDataCodec # 分割字节粘包拆包 ├── JsonCodec # JSON 消息编解码 ├── WebSocketCodec # WebSocket 编解码 └── MessageCodec # 消息编解码 IMatchQueue / DefaultMatchQueue # 消息匹配队列（请求响应配对） HttpServer # 轻量级 HTTP 服务器 ├── HttpRouter # 路由 ├── StaticFilesHandler # 静态文件 ├── ControllerHandler # MVC 控制器 └── CorsMiddleware 等 # 中间件 TinyHttpClient # 极简 HTTP 客户端 DnsHttpHandler # 自定义 DNS 解析处理器 HttpTraceHandler # APM 追踪处理器 WebSocket / WebSocketClient # WebSocket 支持 ``` ### 2.11 Web 工具（M11） ``` JwtBuilder # JWT 令牌生成/解码/验证 TokenProvider # 分布式数字签名令牌 WebClientX # 增强型 HTTP 下载（多线程断点续传） PluginHelper # 插件加载与配置辅助 IObjectStorage (接口) # 对象存储抽象 └── EasyClient # 文件存储 HTTP 客户端（对接 EasyIO/OSS） TokenHttpFilter # HTTP 令牌过滤器（自动注入与续期） ``` ### 2.12 压缩归档（M12） ``` TarFile # Tar/Tar.Gz 归档操作 SevenZip # 7z 压缩解压（自动下载 7z.exe） ``` ### 2.13 RPC 通信（M13） ``` ApiHttpClient # 多节点 HTTP API 客户端 ILoadBalancer # 负载均衡接口 ├── FailoverLoadBalancer # 故障转移 ├── RoundRobinLoadBalancer # 加权轮询 └── RaceLoadBalancer # 竞速模式 IServiceResolver # 服务发现与客户端实例管理 ApiHelper # API 调用辅助方法 ``` ## 3. 关键设计决策 | 决策 | 选择 | 理由 | |------|------|------| | 项目结构 | 单项目 + 目录分区 | 符合两层起步理念，减少维护成本 | | 命名空间 | 每目录一个独立命名空间 | 清晰模块边界，便于按需引用 | | 多目标框架 | net45~net10.0（17 个 TFM） | 最大兼容性，Stub 目录填充缺失类型 | | 日志设计 | `ILog` 接口 + `XTrace` 静态门面 | 兼顾 DI 注入和静态便捷访问 | | 缓存设计 | `ICache` 统一接口 | 内存/Redis/自定义实现可互换 | | 序列化 | 自研高性能实现 | 避免依赖第三方库，控制性能 | | 网络库 | 全异步 Socket | 单机实测 2266 万 tps | | 数据包 | `IPacket` 零拷贝切片 | 网络层核心性能优化点 | | IoC | `ObjectContainer` 自研 | 轻量级，兼容 `IServiceProvider` | | 负载均衡 | 故障转移/加权轮询/竞速 | 覆盖不同场景需求 | ## 4. 组件依赖关系 ``` ┌─────────────────┐ │ M1 基础扩展 │ ← 零依赖，被所有模块使用 └────────┬────────┘ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ M2 日志 │ │ M3 定时 │ │ M4 序列化│ └────┬─────┘ └──────────┘ └────┬─────┘ │ │ ┌────┴─────┐ ┌──────┴──────┐ │ M5 配置 │ │ M6 安全加密 │ └────┬─────┘ └──────┬──────┘ │ │ ┌────┴──────────────┐ │ │ M7 应用框架 │ │ └────┬──────────────┘ │ │ │ ┌────┴──────────────┐ │ │ M8 缓存系统 │◄───────────┘ └────┬──────────────┘ │ ┌────┴──────────────┐ │ M9 数据与算法 │ └────┬──────────────┘ │ ┌────┼────────────────┐ ▼ ▼ ▼ ┌──────┐ ┌──────────┐ ┌──────────┐ │M10 │ │M11 Web │ │M13 RPC │ │网络 │ │工具 │ │通信 │ └──┬───┘ └──────────┘ └──────────┘ │ ▼ ┌──────────┐ │M12 压缩 │ │归档 │ └──────────┘ ``` ## 5. 编码约定 见项目根目录 `.editorconfig` 和 `global.json`。 | 约定 | 说明 | |------|------| | 类型名 | .NET 正式名：`String`/`Int32`/`Boolean`（非 `string`/`int`/`bool`） | | Nullable | 全局启用 `<Nullable>enable</Nullable>` | | 语言版本 | `<LangVersion>latest</LangVersion>`（C# 14） | | 文档注释 | XML 注释所有 public/protected 成员，`<summary>` 同行闭合 | | 签名 | 强命名（`newlife.snk`） |