{"id":30668241,"url":"https://github.com/gameframex/gameframex.foundation","last_synced_at":"2026-04-01T19:41:08.571Z","repository":{"id":272742701,"uuid":"917584817","full_name":"GameFrameX/GameFrameX.Foundation","owner":"GameFrameX","description":"GameFrameX 的基建库","archived":false,"fork":false,"pushed_at":"2026-03-17T10:36:10.000Z","size":2012,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-18T01:13:47.011Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GameFrameX.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-16T09:12:38.000Z","updated_at":"2026-03-17T10:36:13.000Z","dependencies_parsed_at":"2026-01-02T23:07:42.558Z","dependency_job_id":null,"html_url":"https://github.com/GameFrameX/GameFrameX.Foundation","commit_stats":null,"previous_names":["gameframex/gameframex.foundation"],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/GameFrameX/GameFrameX.Foundation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2FGameFrameX.Foundation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2FGameFrameX.Foundation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2FGameFrameX.Foundation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2FGameFrameX.Foundation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GameFrameX","download_url":"https://codeload.github.com/GameFrameX/GameFrameX.Foundation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2FGameFrameX.Foundation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-31T23:46:55.365Z","updated_at":"2026-04-01T19:41:08.548Z","avatar_url":"https://github.com/GameFrameX.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GameFrameX.Foundation\r\n\r\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\r\n[![.NET](https://img.shields.io/badge/.NET-10.0-purple.svg)](https://dotnet.microsoft.com/)\r\n\r\n### 📦 程序集概览\r\n\r\n| 程序集                                      | 功能描述          | NuGet 包名                                   | 版本                                                                                                                                                                | 下载次数                                                                                                                                                               |\r\n|------------------------------------------|---------------|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| GameFrameX.Foundation.Encryption         | 加密工具库         | `GameFrameX.Foundation.Encryption`         | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Encryption.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Encryption/)                 | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Encryption.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Encryption/)                 |\r\n| GameFrameX.Foundation.Extensions         | 扩展方法库         | `GameFrameX.Foundation.Extensions`         | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Extensions.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Extensions/)                 | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Extensions.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Extensions/)                 |\r\n| GameFrameX.Foundation.Hash               | 哈希工具库         | `GameFrameX.Foundation.Hash`               | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Hash.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Hash/)                             | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Hash.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Hash/)                             |\r\n| GameFrameX.Foundation.Http.Extension     | HttpClient 扩展 | `GameFrameX.Foundation.Http.Extension`     | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Http.Extension.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Http.Extension/)         | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Http.Extension.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Http.Extension/)         |\r\n| GameFrameX.Foundation.Http.Normalization | HTTP 消息标准化    | `GameFrameX.Foundation.Http.Normalization` | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Http.Normalization.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Http.Normalization/) | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Http.Normalization.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Http.Normalization/) |\r\n| GameFrameX.Foundation.Json               | JSON 序列化工具    | `GameFrameX.Foundation.Json`               | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Json.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Json/)                             | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Json.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Json/)                             |\r\n| GameFrameX.Foundation.Localization       | 本地化框架         | `GameFrameX.Foundation.Localization`       | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Localization.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Localization/)             | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Localization.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Localization/)             |\r\n| GameFrameX.Foundation.Logger             | Serilog 日志配置  | `GameFrameX.Foundation.Logger`             | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Logger.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Logger/)                         | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Logger.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Logger/)                         |\r\n| GameFrameX.Foundation.Options            | 命令行参数处理       | `GameFrameX.Foundation.Options`            | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Options.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Options/)                       | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Options.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Options/)                       |\r\n| GameFrameX.Foundation.Orm.Attribute      | ORM 特性标注      | `GameFrameX.Foundation.Orm.Attribute`      | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Orm.Attribute.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Orm.Attribute/)           | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Orm.Attribute.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Orm.Attribute/)           |\r\n| GameFrameX.Foundation.Orm.Entity         | ORM 实体基类      | `GameFrameX.Foundation.Orm.Entity`         | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Orm.Entity.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Orm.Entity/)                 | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Orm.Entity.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Orm.Entity/)                 |\r\n| GameFrameX.Foundation.Utility            | 通用工具类         | `GameFrameX.Foundation.Utility`            | [![NuGet](https://img.shields.io/nuget/v/GameFrameX.Foundation.Utility.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Utility/)                       | [![NuGet](https://img.shields.io/nuget/dt/GameFrameX.Foundation.Utility.svg)](https://www.nuget.org/packages/GameFrameX.Foundation.Utility/)                       |\r\n\r\nGameFrameX 的基础工具库，提供了一系列高性能、易用的基础组件和工具类，涵盖加密、哈希、HTTP、JSON、日志等常用功能。\r\n\r\n## 🚀 快速开始\r\n\r\n### 安装\r\n\r\n通过 NuGet 包管理器安装所需的组件：\r\n\r\n```bash\r\n# 安装加密工具库\r\ndotnet add package GameFrameX.Foundation.Encryption\r\n\r\n# 安装扩展方法库\r\ndotnet add package GameFrameX.Foundation.Extensions\r\n\r\n# 安装哈希工具库\r\ndotnet add package GameFrameX.Foundation.Hash\r\n\r\n# 安装 JSON 工具库\r\ndotnet add package GameFrameX.Foundation.Json\r\n\r\n# 安装本地化框架\r\ndotnet add package GameFrameX.Foundation.Localization\r\n\r\n# 安装日志工具库\r\ndotnet add package GameFrameX.Foundation.Logger\r\n\r\n# 安装命令行参数处理库\r\ndotnet add package GameFrameX.Foundation.Options\r\n\r\n# 安装 HTTP 扩展\r\ndotnet add package GameFrameX.Foundation.Http.Extension\r\n\r\n# 安装 HTTP 消息标准化\r\ndotnet add package GameFrameX.Foundation.Http.Normalization\r\n```\r\n\r\n### 基本使用\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Encryption;\r\nusing GameFrameX.Foundation.Extensions;\r\nusing GameFrameX.Foundation.Hash;\r\nusing GameFrameX.Foundation.Json;\r\nusing GameFrameX.Foundation.Localization.Core;\r\nusing GameFrameX.Foundation.Logger;\r\nusing GameFrameX.Foundation.Options;\r\n\r\n// AES 加密\r\nstring encrypted = AesHelper.Encrypt(\"Hello World\", \"your-key\");\r\nstring decrypted = AesHelper.Decrypt(encrypted, \"your-key\");\r\n\r\n// 扩展方法使用\r\nvar list = new List\u003cint\u003e { 1, 2, 3, 4, 5 };\r\nvar randomItem = list.RandomElement(); // 随机获取元素\r\nvar isNullOrEmpty = myString.IsNullOrEmpty(); // 字符串检查\r\n\r\n// 字符串扩展\r\nstring base64 = \"SGVsbG8gV29ybGQ=\";\r\nstring urlSafe = base64.ToUrlSafeBase64(); // URL安全Base64\r\nstring centered = \"Hello\".CenterAlignedText(20); // 居中对齐\r\n\r\n// 对象验证\r\nobject obj = GetSomeObject();\r\nobj.ThrowIfNull(nameof(obj)); // 空值检查\r\nint value = 50;\r\nvalue.CheckRange(1, 100); // 范围检查\r\n\r\n// 高性能字节操作\r\nSpan\u003cbyte\u003e buffer = stackalloc byte[8];\r\nint offset = 0;\r\nbuffer.WriteUIntValue(12345u, ref offset);\r\nbuffer.WriteFloatValue(3.14f, ref offset);\r\n\r\n// 双向字典\r\nvar biDict = new BidirectionalDictionary\u003cstring, int\u003e();\r\nbiDict.TryAdd(\"one\", 1);\r\nif (biDict.TryGetKey(1, out string key)) { /* 反向查找 */ }\r\n\r\n// 命令行参数处理\r\nvar builder = new OptionsBuilder\u003cAppConfig\u003e(args);\r\nvar config = builder.Build();\r\n\r\n// SHA-256 哈希\r\nstring hash = Sha256Helper.ComputeHash(\"Hello World\");\r\n\r\n// JSON 序列化\r\nstring json = JsonHelper.Serialize(myObject);\r\nMyClass obj = JsonHelper.Deserialize\u003cMyClass\u003e(json);\r\n\r\n// 本地化字符串获取\r\nvar successMessage = LocalizationService.GetString(\"Success\");\r\nvar errorMessage = LocalizationService.GetString(\"Utility.Exceptions.TimestampOutOfRange\");\r\nvar formattedMessage = LocalizationService.GetString(\"Encryption.InvalidKeySize\", 128, 256);\r\n\r\n// 日志记录\r\nLogHandler.Create(LogOptions.Default);\r\nLogHelper.Info(\"应用程序启动\");\r\n```\r\n\r\n## 📚 详细文档\r\n\r\n### 🧩 扩展方法库 (GameFrameX.Foundation.Extensions)\r\n\r\n提供丰富的扩展方法集合，增强 .NET 基础类型的功能，提高开发效率和代码可读性。\r\n\r\n#### 核心组件概览\r\n\r\n| 组件           | 文件名                                                               | 主要功能                           |\r\n|--------------|-------------------------------------------------------------------|--------------------------------|\r\n| **集合扩展**     | `CollectionExtensions.cs`                                         | 为各种集合类型提供便捷操作方法                |\r\n| **字符串扩展**    | `StringExtensions.cs`                                             | 增强字符串处理能力，包含URL安全Base64、居中对齐等  |\r\n| **对象扩展**     | `ObjectExtensions.cs`                                             | 提供对象验证和数值范围检查                  |\r\n| **类型扩展**     | `TypeExtensions.cs`                                               | 类型检查和反射相关扩展方法                  |\r\n| **枚举扩展**     | `IEnumerableExtensions.cs`                                        | LINQ 增强和集合操作，支持交集、差集等          |\r\n| **字典扩展**     | `IDictionaryExtensions.cs`                                        | 字典操作增强，支持合并、条件移除等              |\r\n| **列表扩展**     | `ListExtensions.cs`                                               | 列表特定的扩展方法                      |\r\n| **字节扩展**     | `ByteExtensions.cs`                                               | 字节数组操作，包含子数组提取等                |\r\n| **Span扩展**   | `SpanExtensions.cs`                                               | 高性能内存操作，支持各种数据类型读写，包含大端序和小端序支持 |\r\n| **只读Span扩展** | `ReadOnlySpanExtensions.cs`                                       | 只读内存的高性能读取操作                   |\r\n| **序列读取器扩展**  | `SequenceReaderExtensions.cs`                                     | 序列数据的便捷读取方法                    |\r\n| **双向字典**     | `BidirectionalDictionary.cs`                                      | 支持双向查找的字典实现                    |\r\n| **查找表**      | `LookupX.cs`                                                      | 增强的一对多关系查找表                    |\r\n| **并发队列**     | `ConcurrentLimitedQueue.cs`                                       | 线程安全的有限容量队列                    |\r\n| **可空字典**     | `NullableDictionary.cs`\u003cbr/\u003e`NullableConcurrentDictionary.cs`     | 支持空值的字典实现                      |\r\n| **可释放字典**    | `DisposableDictionary.cs`\u003cbr/\u003e`DisposableConcurrentDictionary.cs` | 值可被自动释放的字典                     |\r\n| **常量定义**     | `ConstBaseTypeSize.cs`                                            | 基础数据类型字节大小常量                   |\r\n| **空对象模式**    | `NullObject.cs`                                                   | 类型安全的空对象实现                     |\r\n| **自定义异常**    | `ArgumentAlreadyException.cs`                                     | 参数已存在异常类型                      |\r\n\r\n#### 集合扩展功能\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Extensions;\r\n\r\n// 集合操作\r\nvar list = new List\u003cint\u003e { 1, 2, 3, 4, 5 };\r\nvar randomItem = list.RandomElement(); // 随机获取元素\r\nvar isEmpty = list.IsNullOrEmpty(); // 检查是否为空\r\n\r\n// 字典扩展\r\nvar dict = new Dictionary\u003cstring, int\u003e();\r\ndict.Merge(\"key\", 10, (old, new) =\u003e old + new); // 合并值\r\nvar value = dict.GetOrAdd(\"key\", k =\u003e 42); // 获取或添加\r\ndict.RemoveIf((k, v) =\u003e v \u003e 100); // 条件移除\r\n\r\n// HashSet 扩展\r\nvar hashSet = new HashSet\u003cint\u003e();\r\nhashSet.AddRange(new[] { 1, 2, 3, 4, 5 }); // 批量添加\r\n```\r\n\r\n#### 字符串扩展功能\r\n\r\n```csharp\r\n// 字符串检查\r\nstring text = \"Hello World\";\r\nbool isEmpty = text.IsNullOrEmpty();\r\nbool isEmptyOrWhitespace = text.IsNullOrEmptyOrWhiteSpace();\r\nbool hasContent = text.IsNotNullOrEmptyOrWhiteSpace();\r\n\r\n// 字符串处理\r\nstring base64 = \"SGVsbG8gV29ybGQ=\";\r\nstring urlSafe = base64.ToUrlSafeBase64(); // 转换为 URL 安全格式\r\nstring restored = urlSafe.FromUrlSafeBase64(); // 还原标准格式\r\n\r\n// 字符串操作\r\nstring centered = \"Hello\".CenterAlignedText(20); // 居中对齐\r\nstring cleaned = \"Hello World   \".RemoveWhiteSpace(); // 移除空白字符\r\nstring trimmed = \"Hello!\".RemoveSuffix('!'); // 移除后缀\r\n\r\n// 字符重复\r\nstring repeated = 'A'.RepeatChar(5); // \"AAAAA\"\r\n```\r\n\r\n#### 对象验证和范围检查\r\n\r\n```csharp\r\n// 空值检查\r\nobject obj = GetSomeObject();\r\nif (obj.IsNotNull())\r\n{\r\n    // 对象不为空时的处理\r\n}\r\n\r\n// 参数验证\r\nobj.ThrowIfNull(nameof(obj)); // 为空时抛出异常\r\n\r\n// 数值范围检查\r\nint value = 50;\r\nvalue.CheckRange(1, 100); // 检查范围，超出时抛出异常\r\nbool inRange = value.IsRange(1, 100); // 检查是否在范围内\r\n\r\n// 支持多种数值类型\r\nuint uintValue = 25;\r\nuintValue.CheckRange(0, 50);\r\n\r\nlong longValue = 1000;\r\nlongValue.CheckRange(500, 2000);\r\n```\r\n\r\n#### 类型检查扩展\r\n\r\n```csharp\r\n// 泛型接口检查\r\nType listType = typeof(List\u003cstring\u003e);\r\nType genericListType = typeof(List\u003c\u003e);\r\nbool implementsGeneric = listType.HasImplementedRawGeneric(genericListType);\r\n\r\n// 接口实现检查\r\nType stringType = typeof(string);\r\nType comparableType = typeof(IComparable);\r\nbool implementsInterface = stringType.IsImplWithInterface(comparableType);\r\n```\r\n\r\n#### LINQ 增强扩展\r\n\r\n```csharp\r\n// 交集操作\r\nvar list1 = new[] { 1, 2, 3, 4, 5 };\r\nvar list2 = new[] { 3, 4, 5, 6, 7 };\r\nvar intersection = list1.IntersectBy(list2, x =\u003e x); // 按键取交集\r\n\r\n// 多集合交集\r\nvar collections = new[] { list1, list2, new[] { 4, 5, 6 } };\r\nvar allIntersection = collections.IntersectAll(); // 所有集合的交集\r\n\r\n// 差集操作\r\nvar difference = list1.ExceptBy(list2, (x, y) =\u003e x == y);\r\n\r\n// 批量添加\r\nvar collection = new List\u003cint\u003e();\r\ncollection.AddRange(1, 2, 3, 4, 5); // 使用 params 参数\r\ncollection.AddRange(new[] { 6, 7, 8 }); // 使用数组\r\n```\r\n\r\n#### 双向字典\r\n\r\n```csharp\r\n// 创建双向字典\r\nvar biDict = new BidirectionalDictionary\u003cstring, int\u003e();\r\n\r\n// 添加键值对\r\nbiDict.TryAdd(\"one\", 1);\r\nbiDict.TryAdd(\"two\", 2);\r\n\r\n// 双向查找\r\nif (biDict.TryGetValue(\"one\", out int value))\r\n{\r\n    Console.WriteLine($\"Key 'one' maps to {value}\");\r\n}\r\n\r\nif (biDict.TryGetKey(1, out string key))\r\n{\r\n    Console.WriteLine($\"Value 1 maps to '{key}'\");\r\n}\r\n\r\n// 清空字典\r\nbiDict.Clear();\r\n```\r\n\r\n#### 高性能扩展\r\n\r\n```csharp\r\n// Span 和 ReadOnlySpan 扩展\r\nReadOnlySpan\u003cbyte\u003e span = stackalloc byte[] { 1, 2, 3, 4, 5 };\r\n// 提供针对 Span 的高性能操作扩展\r\n\r\n// 序列读取器扩展\r\n// 为 SequenceReader 提供便捷的读取方法\r\n```\r\n\r\n#### 字节操作扩展\r\n\r\n```csharp\r\n// 字节数组扩展\r\nbyte[] data = { 1, 2, 3, 4, 5 };\r\nbyte[] subArray = data.SubArray(1, 3); // 获取子数组\r\n\r\n// Span 和 ReadOnlySpan 扩展 - 高性能字节操作\r\nSpan\u003cbyte\u003e buffer = stackalloc byte[16];\r\nint offset = 0;\r\n\r\n// 写入各种数据类型（支持大端序和小端序）\r\nbuffer.WriteUIntValue(12345u, ref offset);\r\nbuffer.WriteFloatValue(3.14f, ref offset);\r\nbuffer.WriteUIntBigEndianValue(12345u, ref offset); // 大端序写入\r\nbuffer.WriteFloatBigEndianValue(3.14f, ref offset); // 大端序写入\r\n\r\n// 读取数据类型\r\noffset = 0;\r\nuint value = buffer.ReadUIntValue(ref offset);\r\nfloat floatValue = buffer.ReadFloatValue(ref offset);\r\nuint bigEndianValue = buffer.ReadUIntBigEndianValue(ref offset); // 大端序读取\r\n\r\n// ReadOnlySpan 读取操作\r\nReadOnlySpan\u003cbyte\u003e readBuffer = buffer;\r\noffset = 0;\r\nuint readValue = readBuffer.ReadUIntValue(ref offset);\r\nfloat readFloatValue = readBuffer.ReadFloatBigEndianValue(ref offset);\r\n```\r\n\r\n#### 序列读取器扩展\r\n\r\n```csharp\r\n// 为 SequenceReader 提供便捷的读取方法\r\n// 支持带长度前缀的字节数组读取\r\n// 提供 TryPeek 方法进行非破坏性读取\r\n```\r\n\r\n#### 特殊工具类\r\n\r\n- **ConstBaseTypeSize**: 基础数据类型字节大小常量定义，包含所有.NET基础类型的字节大小\r\n- **NullObject**: 空对象模式实现，提供类型安全的空对象\r\n- **NullableConcurrentDictionary**: 支持空值的线程安全并发字典\r\n- **NullableDictionary**: 支持空值的普通字典\r\n- **LookupX**: 增强的查找表实现，支持一对多关系映射\r\n- **ArgumentAlreadyException**: 参数已存在异常，用于参数验证场景\r\n- **ConcurrentLimitedQueue**: 线程安全的有限容量队列，自动移除最旧元素\r\n- **DisposableConcurrentDictionary/DisposableDictionary**: 值可被自动释放的字典类型\r\n\r\n### 🔐 加密工具库 (GameFrameX.Foundation.Encryption)\r\n\r\n提供多种加密算法的实现，确保数据安全传输和存储。\r\n\r\n#### 支持的算法\r\n\r\n- **AES 加密** (`AesHelper`): 对称加密算法，支持字符串和字节数组\r\n- **RSA 加密** (`RsaHelper`): 非对称加密算法，支持密钥对生成、加密解密、数字签名\r\n- **DSA 签名** (`DsaHelper`): 数字签名算法，支持签名和验证\r\n- **SM2/SM4 加密** (`Sm2Helper`/`Sm4Helper`): 国密算法实现\r\n    - SM2: 非对称加密算法\r\n    - SM4: 对称加密算法，支持 ECB/CBC 模式\r\n- **XOR 加密** (`XorHelper`): 异或加密，支持快速加密和完整加密模式\r\n\r\n#### 使用示例\r\n\r\n```csharp\r\n// AES 加密\r\nstring encrypted = AesHelper.Encrypt(\"敏感数据\", \"your-secret-key\");\r\nstring decrypted = AesHelper.Decrypt(encrypted, \"your-secret-key\");\r\n\r\n// RSA 加密\r\nvar keys = RsaHelper.Make();\r\nstring encrypted = RsaHelper.Encrypt(keys[\"publicKey\"], \"Hello World\");\r\nstring decrypted = RsaHelper.Decrypt(keys[\"privateKey\"], encrypted);\r\n\r\n// SM4 加密\r\nstring encrypted = Sm4Helper.EncryptCbc(\"your-key\", \"Hello World\");\r\nstring decrypted = Sm4Helper.DecryptCbc(\"your-key\", encrypted);\r\n```\r\n\r\n### 🔗 哈希工具库 (GameFrameX.Foundation.Hash)\r\n\r\n提供多种哈希算法实现，适用于数据完整性校验、快速查找等场景。\r\n\r\n#### 支持的算法\r\n\r\n- **MD5** (`Md5Helper`): 128位哈希值，支持加盐\r\n- **SHA 系列**:\r\n    - SHA-1 (`Sha1Helper`): 160位哈希值\r\n    - SHA-256 (`Sha256Helper`): 256位哈希值\r\n    - SHA-512 (`Sha512Helper`): 512位哈希值\r\n- **HMAC-SHA256** (`HmacSha256Helper`): 基于密钥的消息认证码\r\n- **CRC 校验** (`CrcHelper`): CRC32/CRC64 循环冗余校验\r\n- **MurmurHash3** (`MurmurHash3Helper`): 高性能非加密哈希\r\n- **xxHash** (`XxHashHelper`): 超高性能哈希算法，支持32/64/128位\r\n\r\n#### 使用示例\r\n\r\n```csharp\r\n// MD5 哈希\r\nstring md5Hash = Md5Helper.Hash(\"Hello World\");\r\nstring saltedHash = Md5Helper.HashWithSalt(\"Hello World\", \"salt\");\r\n\r\n// SHA-256 哈希\r\nstring sha256Hash = Sha256Helper.ComputeHash(\"Hello World\");\r\n\r\n// HMAC-SHA256\r\nstring hmacHash = HmacSha256Helper.Hash(\"message\", \"secret-key\");\r\n\r\n// xxHash (高性能)\r\nulong xxHash = XxHashHelper.Hash64(\"Hello World\");\r\n```\r\n\r\n### 🌐 HTTP 工具库\r\n\r\n#### HTTP 扩展 (GameFrameX.Foundation.Http.Extension)\r\n\r\n为 HttpClient 提供便捷的扩展方法，简化 JSON 数据的发送和接收。\r\n\r\n```csharp\r\n// POST JSON 请求\r\nstring response = await httpClient.PostJsonToStringAsync\u003cMyClass\u003e(url, myObject);\r\n```\r\n\r\n#### HTTP 消息标准化 (GameFrameX.Foundation.Http.Normalization)\r\n\r\n提供统一的 HTTP 响应格式，包含 `code`、`message` 和 `data` 字段，适用于 GameFrameX 生态系统。\r\n\r\n### 📄 JSON 序列化 (GameFrameX.Foundation.Json)\r\n\r\n基于 `System.Text.Json` 的高性能序列化工具，提供优化的默认配置。\r\n\r\n#### 特性\r\n\r\n- 高性能序列化/反序列化\r\n- 枚举序列化为字符串\r\n- 忽略 null 值属性\r\n- 忽略循环引用\r\n- 属性名称大小写不敏感\r\n- 提供格式化和紧凑两种输出模式\r\n\r\n#### 使用示例\r\n\r\n```csharp\r\n// 序列化\r\nstring json = JsonHelper.Serialize(myObject);\r\nstring formattedJson = JsonHelper.Serialize(myObject, JsonHelper.FormatOptions);\r\n\r\n// 反序列化\r\nMyClass obj = JsonHelper.Deserialize\u003cMyClass\u003e(json);\r\n\r\n// 安全的反序列化\r\nif (JsonHelper.TryDeserialize\u003cMyClass\u003e(json, out var result))\r\n{\r\n    // 处理结果\r\n}\r\n```\r\n\r\n### 🌐 本地化框架 (GameFrameX.Foundation.Localization)\r\n\r\n提供轻量级、高性能的本地化解决方案，支持零配置使用和懒加载机制，为整个 GameFrameX.Foundation 生态系统提供统一的本地化支持。\r\n\r\n#### 主要特性\r\n\r\n- **零配置使用**: 无需任何初始化配置，自动发现和加载本地化资源\r\n- **懒加载机制**: 首次使用时才加载资源，启动性能优异\r\n- **多语言支持**: 内置中文（简体）和英文支持，可扩展更多语言\r\n- **线程安全**: 支持并发访问，适用于多线程环境\r\n- **高度可扩展**: 支持自定义资源提供者，灵活的优先级管理\r\n- **优先级解析**: 自定义提供者 \u003e 程序集资源 \u003e 默认资源\r\n\r\n#### 核心组件\r\n\r\n| 组件         | 文件名                           | 功能                  |\r\n|------------|-------------------------------|---------------------|\r\n| **本地化服务**  | `LocalizationService.cs`      | 统一的本地化入口点，提供静态方法API |\r\n| **资源管理器**  | `ResourceManager.cs`          | 管理多个资源提供者，实现优先级解析   |\r\n| **默认提供者**  | `DefaultResourceProvider.cs`  | 提供英文默认消息，包含50+常用消息  |\r\n| **程序集提供者** | `AssemblyResourceProvider.cs` | 从.resx文件加载本地化资源     |\r\n\r\n#### 基础使用\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Localization.Core;\r\n\r\n// 获取简单的本地化字符串\r\nvar successMessage = LocalizationService.GetString(\"Success\");\r\nConsole.WriteLine(successMessage); // 根据当前文化显示 \"Success\" 或 \"成功\"\r\n\r\n// 带参数的格式化消息\r\nvar errorMessage = LocalizationService.GetString(\"ArgumentNull\", \"username\");\r\nConsole.WriteLine(errorMessage); // \"Value cannot be null. (Parameter 'username')\"\r\n\r\n// 如果键不存在，返回键名本身\r\nvar unknown = LocalizationService.GetString(\"Some.Unknown.Key\");\r\nConsole.WriteLine(unknown); // 输出: \"Some.Unknown.Key\"\r\n```\r\n\r\n#### 异常处理中的本地化\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility.Localization;\r\n\r\npublic class UserService\r\n{\r\n    public void ValidateUserInput(string input)\r\n    {\r\n        if (string.IsNullOrEmpty(input))\r\n        {\r\n            throw new ArgumentException(\r\n                LocalizationService.GetString(LocalizationKeys.Exceptions.TimestampOutOfRange),\r\n                nameof(input));\r\n        }\r\n\r\n        // 其他验证逻辑...\r\n    }\r\n}\r\n```\r\n\r\n#### 模块集成本地化\r\n\r\n##### 1. 定义本地化键\r\n\r\n```csharp\r\n// YourModule/Localization/Keys.cs\r\nnamespace GameFrameX.Foundation.YourModule.Localization;\r\n\r\npublic static class LocalizationKeys\r\n{\r\n    public static class Validation\r\n    {\r\n        public const string EmailRequired = \"YourModule.Validation.EmailRequired\";\r\n        public const string EmailInvalid = \"YourModule.Validation.EmailInvalid\";\r\n    }\r\n\r\n    public static class Messages\r\n    {\r\n        public const string UserCreated = \"YourModule.Messages.UserCreated\";\r\n        public const string OperationFailed = \"YourModule.Messages.OperationFailed\";\r\n    }\r\n}\r\n```\r\n\r\n##### 2. 创建资源文件\r\n\r\n在项目中创建 `Localization/Messages/Resources.resx` 和 `Localization/Messages/Resources.zh-CN.resx`：\r\n\r\n```xml\r\n\u003c!-- Resources.resx (默认英文) --\u003e\r\n\u003croot\u003e\r\n  \u003cdata name=\"YourModule.Validation.EmailRequired\" xml:space=\"preserve\"\u003e\r\n    \u003cvalue\u003eEmail address is required\u003c/value\u003e\r\n  \u003c/data\u003e\r\n  \u003cdata name=\"YourModule.Messages.UserCreated\" xml:space=\"preserve\"\u003e\r\n    \u003cvalue\u003eUser '{0}' has been created successfully\u003c/value\u003e\r\n  \u003c/data\u003e\r\n\u003c/root\u003e\r\n```\r\n\r\n```xml\r\n\u003c!-- Resources.zh-CN.resx (中文) --\u003e\r\n\u003croot\u003e\r\n  \u003cdata name=\"YourModule.Validation.EmailRequired\" xml:space=\"preserve\"\u003e\r\n    \u003cvalue\u003e邮箱地址是必填项\u003c/value\u003e\r\n  \u003c/data\u003e\r\n  \u003cdata name=\"YourModule.Messages.UserCreated\" xml:space=\"preserve\"\u003e\r\n    \u003cvalue\u003e用户 '{0}' 已成功创建\u003c/value\u003e\r\n  \u003c/data\u003e\r\n\u003c/root\u003e\r\n```\r\n\r\n##### 3. 在业务逻辑中使用\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Localization.Core;\r\nusing GameFrameX.Foundation.YourModule.Localization;\r\n\r\npublic class UserService\r\n{\r\n    public void CreateUser(UserDto userDto)\r\n    {\r\n        if (string.IsNullOrEmpty(userDto.Email))\r\n        {\r\n            throw new ValidationException(\r\n                LocalizationService.GetString(LocalizationKeys.Validation.EmailRequired));\r\n        }\r\n\r\n        // 创建用户逻辑...\r\n\r\n        var successMessage = LocalizationService.GetString(\r\n            LocalizationKeys.Messages.UserCreated, userDto.Username);\r\n        Console.WriteLine(successMessage);\r\n    }\r\n}\r\n```\r\n\r\n#### 自定义资源提供者\r\n\r\n```csharp\r\npublic class DatabaseResourceProvider : IResourceProvider\r\n{\r\n    private readonly IDbConnection _connection;\r\n\r\n    public DatabaseResourceProvider(IDbConnection connection)\r\n    {\r\n        _connection = connection;\r\n    }\r\n\r\n    public string GetString(string key)\r\n    {\r\n        var culture = CultureInfo.CurrentCulture.Name;\r\n        var sql = \"SELECT localized_text FROM localization_strings WHERE key = @key AND culture = @culture\";\r\n        return _connection.ExecuteScalar\u003cstring\u003e(sql, new { key, culture });\r\n    }\r\n}\r\n\r\n// 注册自定义提供者（具有最高优先级）\r\nvar dbProvider = new DatabaseResourceProvider(yourDbConnection);\r\nLocalizationService.RegisterProvider(dbProvider);\r\n```\r\n\r\n#### 预加载和性能优化\r\n\r\n```csharp\r\n// 应用启动时预加载所有本地化资源（可选）\r\nLocalizationService.EnsureLoaded();\r\n\r\n// 获取本地化系统统计信息\r\nvar stats = LocalizationService.GetStatistics();\r\nConsole.WriteLine($\"提供者已加载: {stats.ProvidersLoaded}\");\r\nConsole.WriteLine($\"总提供者数量: {stats.TotalProviderCount}\");\r\nConsole.WriteLine($\"程序集提供者数量: {stats.AssemblyProviderCount}\");\r\n\r\n// 获取所有提供者信息\r\nvar providers = LocalizationService.GetProviders();\r\nforeach (var provider in providers)\r\n{\r\n    Console.WriteLine($\"提供者: {provider.GetType().Name}\");\r\n}\r\n```\r\n\r\n#### 资源命名约定\r\n\r\n- **模式**: `{模块名}.{类别}.{具体键名}`\r\n- **示例**:\r\n    - `Utility.Exceptions.TimestampOutOfRange`\r\n    - `Encryption.InvalidKeySize`\r\n    - `Authentication.UserNotFound`\r\n    - `Success`\r\n    - `ArgumentNull`\r\n\r\n#### 已集成的模块\r\n\r\n目前以下模块已完成本地化集成：\r\n\r\n| 模块                               | 本地化键数量 | 状态   |\r\n|----------------------------------|--------|------|\r\n| GameFrameX.Foundation.Utility    | 4      | ✅ 完成 |\r\n| GameFrameX.Foundation.Encryption | 20+    | ✅ 完成 |\r\n| GameFrameX.Foundation.Extensions | 7      | ✅ 完成 |\r\n| GameFrameX.Foundation.Hash       | 2      | ✅ 完成 |\r\n\r\n#### 高级功能\r\n\r\n##### 动态语言切换\r\n\r\n```csharp\r\npublic void SwitchLanguage(string cultureCode)\r\n{\r\n    Thread.CurrentThread.CurrentUICulture = new CultureInfo(cultureCode);\r\n    Thread.CurrentThread.CurrentCulture = new CultureInfo(cultureCode);\r\n\r\n    // 可选：预加载新语言的资源\r\n    LocalizationService.EnsureLoaded();\r\n}\r\n```\r\n\r\n##### 监控和诊断\r\n\r\n```csharp\r\npublic class LocalizationDiagnostics\r\n{\r\n    public void PrintStatus()\r\n    {\r\n        var stats = LocalizationService.GetStatistics();\r\n        Console.WriteLine(\"=== 本地化系统状态 ===\");\r\n        Console.WriteLine($\"提供者已加载: {stats.ProvidersLoaded}\");\r\n        Console.WriteLine($\"总提供者数量: {stats.TotalProviderCount}\");\r\n\r\n        var providers = LocalizationService.GetProviders();\r\n        foreach (var provider in providers)\r\n        {\r\n            Console.WriteLine($\"- {provider.GetType().Name}\");\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n#### 最佳实践\r\n\r\n1. **键命名规范**: 使用 `{模块名}.{类别}.{具体键名}` 的命名模式\r\n2. **参数化消息**: 使用 `string.Format` 格式支持参数替换\r\n3. **异常处理**: 在异常消息中集成本地化支持\r\n4. **性能优化**: 应用启动时可选择预加载资源\r\n5. **测试验证**: 为本地化功能编写单元测试\r\n\r\n#### 配置项目文件\r\n\r\n确保项目文件包含本地化资源文件：\r\n\r\n```xml\r\n\u003cPropertyGroup\u003e\r\n  \u003cEnableDefaultEmbeddedResourceItems\u003efalse\u003c/EnableDefaultEmbeddedResourceItems\u003e\r\n\u003c/PropertyGroup\u003e\r\n\r\n\u003cItemGroup\u003e\r\n  \u003cEmbeddedResource Include=\"Localization\\Messages\\*.resx\" /\u003e\r\n\u003c/ItemGroup\u003e\r\n```\r\n\r\n更多详细信息请参考：\r\n\r\n- [本地化框架完整文档](GameFrameX.Foundation.Localization/README.Localization.md)\r\n- [使用示例和最佳实践](GameFrameX.Foundation.Localization/USAGE_EXAMPLES.md)\r\n\r\n### �️ ORM 实体基类 (GameFrameX.Foundation.Orm.Entity)\r\n\r\n提供ORM框架的实体基类和接口定义，支持审计跟踪、软删除、乐观锁等企业级功能。\r\n\r\n#### 核心组件概览\r\n\r\n| 组件           | 文件名                   | 主要功能                          |\r\n|--------------|-----------------------|-------------------------------|\r\n| **实体基类**     | `EntityBase.cs`       | 完整功能的实体基类，包含ID、审计、软删除、版本控制等功能 |\r\n| **实体基类(泛型)** | `EntityBaseId.cs`     | 支持自定义主键类型的实体基类                |\r\n| **实体接口**     | `IEntity.cs`          | 基础实体接口定义，提供ID属性               |\r\n| **审计接口**     | `IAuditableEntity.cs` | 审计功能接口，定义创建时间、更新时间、操作用户等审计字段  |\r\n\r\n#### 实体基类功能\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 继承EntityBase的实体类自动获得完整的企业级功能\r\npublic class User : EntityBase\r\n{\r\n    public string Username { get; set; }\r\n    public string Email { get; set; }\r\n    public string PasswordHash { get; set; }\r\n    \r\n    // 以下属性由EntityBase提供：\r\n    // - long Id                    // 主键ID\r\n    // - DateTime CreateTime        // 创建时间\r\n    // - DateTime UpdateTime        // 更新时间\r\n    // - long CreateUserId          // 创建用户ID\r\n    // - long UpdateUserId          // 更新用户ID\r\n    // - string CreateUserName      // 创建用户名\r\n    // - string UpdateUserName      // 更新用户名\r\n    // - bool IsDelete              // 软删除标记\r\n    // - long Version               // 乐观锁版本号\r\n    // - bool IsEnabled             // 启用状态\r\n}\r\n\r\n// 使用示例\r\nvar user = new User\r\n{\r\n    Username = \"john_doe\",\r\n    Email = \"john@example.com\",\r\n    PasswordHash = \"hashed_password\",\r\n    CreateTime = DateTime.UtcNow,\r\n    CreateUserId = 1,\r\n    CreateUserName = \"admin\",\r\n    IsEnabled = true\r\n};\r\n```\r\n\r\n#### 自定义主键类型\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 使用字符串作为主键\r\npublic class Product : EntityBaseId\u003cstring\u003e\r\n{\r\n    public string Name { get; set; }\r\n    public decimal Price { get; set; }\r\n    public string Description { get; set; }\r\n    \r\n    // Id属性类型为string，由EntityBaseId\u003cstring\u003e提供\r\n}\r\n\r\n// 使用Guid作为主键\r\npublic class Order : EntityBaseId\u003cGuid\u003e\r\n{\r\n    public string OrderNumber { get; set; }\r\n    public decimal TotalAmount { get; set; }\r\n    public DateTime OrderDate { get; set; }\r\n    \r\n    // Id属性类型为Guid，由EntityBaseId\u003cGuid\u003e提供\r\n}\r\n\r\n// 使用示例\r\nvar product = new Product\r\n{\r\n    Id = \"PROD-001\",\r\n    Name = \"笔记本电脑\",\r\n    Price = 5999.99m,\r\n    Description = \"高性能笔记本电脑\"\r\n};\r\n\r\nvar order = new Order\r\n{\r\n    Id = Guid.NewGuid(),\r\n    OrderNumber = \"ORD-20240101-001\",\r\n    TotalAmount = 5999.99m,\r\n    OrderDate = DateTime.UtcNow\r\n};\r\n```\r\n\r\n#### 接口实现\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 实现基础实体接口\r\npublic class Category : IEntity\u003cint\u003e\r\n{\r\n    public int Id { get; set; }\r\n    public string Name { get; set; }\r\n    public string Description { get; set; }\r\n}\r\n\r\n// 实现审计接口\r\npublic class AuditableCategory : IEntity\u003cint\u003e, IAuditableEntity\r\n{\r\n    public int Id { get; set; }\r\n    public string Name { get; set; }\r\n    public string Description { get; set; }\r\n    \r\n    // IAuditableEntity接口要求的属性\r\n    public DateTime CreateTime { get; set; }\r\n    public DateTime UpdateTime { get; set; }\r\n    public long CreateUserId { get; set; }\r\n    public long UpdateUserId { get; set; }\r\n    public string CreateUserName { get; set; }\r\n    public string UpdateUserName { get; set; }\r\n}\r\n```\r\n\r\n#### 企业级功能详解\r\n\r\n##### 1. 审计跟踪 (Audit Trail)\r\n\r\n```csharp\r\n// EntityBase自动提供审计字段\r\npublic class Document : EntityBase\r\n{\r\n    public string Title { get; set; }\r\n    public string Content { get; set; }\r\n}\r\n\r\n// 在业务逻辑中设置审计信息\r\nvar document = new Document\r\n{\r\n    Title = \"重要文档\",\r\n    Content = \"文档内容...\",\r\n    CreateTime = DateTime.UtcNow,\r\n    CreateUserId = currentUser.Id,\r\n    CreateUserName = currentUser.Username,\r\n    UpdateTime = DateTime.UtcNow,\r\n    UpdateUserId = currentUser.Id,\r\n    UpdateUserName = currentUser.Username\r\n};\r\n\r\n// 更新时自动维护审计信息\r\ndocument.Content = \"更新后的内容\";\r\ndocument.UpdateTime = DateTime.UtcNow;\r\ndocument.UpdateUserId = currentUser.Id;\r\ndocument.UpdateUserName = currentUser.Username;\r\ndocument.Version++; // 乐观锁版本递增\r\n```\r\n\r\n##### 2. 软删除 (Soft Delete)\r\n\r\n```csharp\r\n// 软删除：不真正删除记录，而是标记为已删除\r\npublic void SoftDeleteUser(User user)\r\n{\r\n    user.IsDelete = true;\r\n    user.UpdateTime = DateTime.UtcNow;\r\n    user.UpdateUserId = currentUser.Id;\r\n    user.UpdateUserName = currentUser.Username;\r\n    \r\n    // 保存到数据库，记录仍然存在但被标记为已删除\r\n    dbContext.SaveChanges();\r\n}\r\n\r\n// 查询时过滤已删除的记录\r\nvar activeUsers = dbContext.Users\r\n    .Where(u =\u003e !u.IsDelete)\r\n    .ToList();\r\n\r\n// 恢复已删除的记录\r\npublic void RestoreUser(User user)\r\n{\r\n    user.IsDelete = false;\r\n    user.UpdateTime = DateTime.UtcNow;\r\n    user.UpdateUserId = currentUser.Id;\r\n    user.UpdateUserName = currentUser.Username;\r\n    \r\n    dbContext.SaveChanges();\r\n}\r\n```\r\n\r\n##### 3. 乐观锁 (Optimistic Locking)\r\n\r\n```csharp\r\n// 使用Version字段实现乐观锁\r\npublic void UpdateUserWithOptimisticLock(long userId, string newEmail)\r\n{\r\n    var user = dbContext.Users.Find(userId);\r\n    if (user == null) throw new EntityNotFoundException();\r\n    \r\n    var originalVersion = user.Version;\r\n    \r\n    // 修改数据\r\n    user.Email = newEmail;\r\n    user.UpdateTime = DateTime.UtcNow;\r\n    user.UpdateUserId = currentUser.Id;\r\n    user.UpdateUserName = currentUser.Username;\r\n    user.Version++; // 版本号递增\r\n    \r\n    try\r\n    {\r\n        // 保存时检查版本号\r\n        var rowsAffected = dbContext.Database.ExecuteSqlRaw(\r\n            \"UPDATE Users SET Email = {0}, UpdateTime = {1}, UpdateUserId = {2}, UpdateUserName = {3}, Version = {4} \" +\r\n            \"WHERE Id = {5} AND Version = {6}\",\r\n            user.Email, user.UpdateTime, user.UpdateUserId, user.UpdateUserName, user.Version, user.Id, originalVersion);\r\n            \r\n        if (rowsAffected == 0)\r\n        {\r\n            throw new ConcurrencyException(\"数据已被其他用户修改，请刷新后重试\");\r\n        }\r\n    }\r\n    catch (DbUpdateConcurrencyException)\r\n    {\r\n        throw new ConcurrencyException(\"并发冲突，请刷新后重试\");\r\n    }\r\n}\r\n```\r\n\r\n##### 4. 启用状态管理\r\n\r\n```csharp\r\n// 使用IsEnabled字段管理实体的启用状态\r\npublic class Feature : EntityBase\r\n{\r\n    public string Name { get; set; }\r\n    public string Description { get; set; }\r\n    // IsEnabled由EntityBase提供\r\n}\r\n\r\n// 启用/禁用功能\r\npublic void ToggleFeature(long featureId, bool enabled)\r\n{\r\n    var feature = dbContext.Features.Find(featureId);\r\n    if (feature == null) throw new EntityNotFoundException();\r\n    \r\n    feature.IsEnabled = enabled;\r\n    feature.UpdateTime = DateTime.UtcNow;\r\n    feature.UpdateUserId = currentUser.Id;\r\n    feature.UpdateUserName = currentUser.Username;\r\n    feature.Version++;\r\n    \r\n    dbContext.SaveChanges();\r\n}\r\n\r\n// 查询启用的功能\r\nvar enabledFeatures = dbContext.Features\r\n    .Where(f =\u003e f.IsEnabled \u0026\u0026 !f.IsDelete)\r\n    .ToList();\r\n```\r\n\r\n#### 完整使用示例\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Entity;\r\nusing Microsoft.EntityFrameworkCore;\r\n\r\nnamespace MyApplication.Entities\r\n{\r\n    // 用户实体\r\n    public class User : EntityBase\r\n    {\r\n        public string Username { get; set; }\r\n        public string Email { get; set; }\r\n        public string PasswordHash { get; set; }\r\n        public string FirstName { get; set; }\r\n        public string LastName { get; set; }\r\n        public DateTime? LastLoginTime { get; set; }\r\n        \r\n        // 导航属性\r\n        public virtual ICollection\u003cOrder\u003e Orders { get; set; }\r\n        public virtual ICollection\u003cUserRole\u003e UserRoles { get; set; }\r\n    }\r\n    \r\n    // 订单实体（使用Guid主键）\r\n    public class Order : EntityBaseId\u003cGuid\u003e\r\n    {\r\n        public string OrderNumber { get; set; }\r\n        public long UserId { get; set; }\r\n        public decimal TotalAmount { get; set; }\r\n        public DateTime OrderDate { get; set; }\r\n        public OrderStatus Status { get; set; }\r\n        \r\n        // 导航属性\r\n        public virtual User User { get; set; }\r\n        public virtual ICollection\u003cOrderItem\u003e OrderItems { get; set; }\r\n    }\r\n    \r\n    // 订单项实体\r\n    public class OrderItem : EntityBase\r\n    {\r\n        public Guid OrderId { get; set; }\r\n        public string ProductId { get; set; }\r\n        public int Quantity { get; set; }\r\n        public decimal UnitPrice { get; set; }\r\n        public decimal TotalPrice { get; set; }\r\n        \r\n        // 导航属性\r\n        public virtual Order Order { get; set; }\r\n        public virtual Product Product { get; set; }\r\n    }\r\n    \r\n    // 产品实体（使用字符串主键）\r\n    public class Product : EntityBaseId\u003cstring\u003e\r\n    {\r\n        public string Name { get; set; }\r\n        public string Description { get; set; }\r\n        public decimal Price { get; set; }\r\n        public int StockQuantity { get; set; }\r\n        public string CategoryId { get; set; }\r\n        \r\n        // 导航属性\r\n        public virtual Category Category { get; set; }\r\n        public virtual ICollection\u003cOrderItem\u003e OrderItems { get; set; }\r\n    }\r\n    \r\n    // 分类实体（实现接口）\r\n    public class Category : IEntity\u003cstring\u003e, IAuditableEntity\r\n    {\r\n        public string Id { get; set; }\r\n        public string Name { get; set; }\r\n        public string Description { get; set; }\r\n        public string ParentId { get; set; }\r\n        \r\n        // IAuditableEntity接口属性\r\n        public DateTime CreateTime { get; set; }\r\n        public DateTime UpdateTime { get; set; }\r\n        public long CreateUserId { get; set; }\r\n        public long UpdateUserId { get; set; }\r\n        public string CreateUserName { get; set; }\r\n        public string UpdateUserName { get; set; }\r\n        \r\n        // 导航属性\r\n        public virtual Category Parent { get; set; }\r\n        public virtual ICollection\u003cCategory\u003e Children { get; set; }\r\n        public virtual ICollection\u003cProduct\u003e Products { get; set; }\r\n    }\r\n    \r\n    public enum OrderStatus\r\n    {\r\n        Pending = 0,\r\n        Confirmed = 1,\r\n        Shipped = 2,\r\n        Delivered = 3,\r\n        Cancelled = 4\r\n    }\r\n}\r\n\r\n// 业务服务示例\r\nnamespace MyApplication.Services\r\n{\r\n    public class UserService\r\n    {\r\n        private readonly ApplicationDbContext _context;\r\n        private readonly ICurrentUserService _currentUserService;\r\n        \r\n        public UserService(ApplicationDbContext context, ICurrentUserService currentUserService)\r\n        {\r\n            _context = context;\r\n            _currentUserService = currentUserService;\r\n        }\r\n        \r\n        public async Task\u003cUser\u003e CreateUserAsync(string username, string email, string password)\r\n        {\r\n            var currentUser = await _currentUserService.GetCurrentUserAsync();\r\n            \r\n            var user = new User\r\n            {\r\n                Username = username,\r\n                Email = email,\r\n                PasswordHash = HashPassword(password),\r\n                CreateTime = DateTime.UtcNow,\r\n                UpdateTime = DateTime.UtcNow,\r\n                CreateUserId = currentUser.Id,\r\n                UpdateUserId = currentUser.Id,\r\n                CreateUserName = currentUser.Username,\r\n                UpdateUserName = currentUser.Username,\r\n                IsEnabled = true,\r\n                IsDelete = false,\r\n                Version = 1\r\n            };\r\n            \r\n            _context.Users.Add(user);\r\n            await _context.SaveChangesAsync();\r\n            \r\n            return user;\r\n        }\r\n        \r\n        public async Task\u003cUser\u003e UpdateUserAsync(long userId, string email, string firstName, string lastName)\r\n        {\r\n            var user = await _context.Users\r\n                .Where(u =\u003e u.Id == userId \u0026\u0026 !u.IsDelete)\r\n                .FirstOrDefaultAsync();\r\n                \r\n            if (user == null)\r\n                throw new EntityNotFoundException($\"用户 {userId} 不存在\");\r\n            \r\n            var currentUser = await _currentUserService.GetCurrentUserAsync();\r\n            var originalVersion = user.Version;\r\n            \r\n            // 更新字段\r\n            user.Email = email;\r\n            user.FirstName = firstName;\r\n            user.LastName = lastName;\r\n            user.UpdateTime = DateTime.UtcNow;\r\n            user.UpdateUserId = currentUser.Id;\r\n            user.UpdateUserName = currentUser.Username;\r\n            user.Version++;\r\n            \r\n            try\r\n            {\r\n                await _context.SaveChangesAsync();\r\n                return user;\r\n            }\r\n            catch (DbUpdateConcurrencyException)\r\n            {\r\n                throw new ConcurrencyException(\"用户信息已被其他用户修改，请刷新后重试\");\r\n            }\r\n        }\r\n        \r\n        public async Task SoftDeleteUserAsync(long userId)\r\n        {\r\n            var user = await _context.Users\r\n                .Where(u =\u003e u.Id == userId \u0026\u0026 !u.IsDelete)\r\n                .FirstOrDefaultAsync();\r\n                \r\n            if (user == null)\r\n                throw new EntityNotFoundException($\"用户 {userId} 不存在\");\r\n            \r\n            var currentUser = await _currentUserService.GetCurrentUserAsync();\r\n            \r\n            user.IsDelete = true;\r\n            user.UpdateTime = DateTime.UtcNow;\r\n            user.UpdateUserId = currentUser.Id;\r\n            user.UpdateUserName = currentUser.Username;\r\n            user.Version++;\r\n            \r\n            await _context.SaveChangesAsync();\r\n        }\r\n        \r\n        public async Task\u003cList\u003cUser\u003e\u003e GetActiveUsersAsync()\r\n        {\r\n            return await _context.Users\r\n                .Where(u =\u003e u.IsEnabled \u0026\u0026 !u.IsDelete)\r\n                .OrderBy(u =\u003e u.CreateTime)\r\n                .ToListAsync();\r\n        }\r\n        \r\n        private string HashPassword(string password)\r\n        {\r\n            // 实现密码哈希逻辑\r\n            return BCrypt.Net.BCrypt.HashPassword(password);\r\n        }\r\n    }\r\n}\r\n\r\n### 🏷️ ORM 属性标记 (GameFrameX.Foundation.Orm.Attribute)\r\n\r\n提供ORM框架的属性标记，用于标识实体类的特殊功能，如审计跟踪、缓存策略、软删除和版本控制等。\r\n\r\n#### 核心组件概览\r\n\r\n| 组件           | 文件名                    | 主要功能                                    |\r\n|--------------|------------------------|-----------------------------------------|\r\n| **审计表属性**    | `AuditTableAttribute.cs` | 标记实体类支持审计跟踪功能，记录数据变更历史                  |\r\n| **缓存表属性**    | `CacheTableAttribute.cs` | 标记实体类支持缓存策略，提升数据访问性能                    |\r\n| **软删除属性**    | `SoftDeleteAttribute.cs` | 标记实体类支持软删除功能，逻辑删除而非物理删除                 |\r\n| **版本控制属性**   | `VersionControlAttribute.cs` | 标记实体类支持数据版本管理，实现乐观锁和并发控制               |\r\n\r\n#### 审计表属性 (AuditTableAttribute)\r\n\r\n用于标记需要进行审计跟踪的实体类，系统会自动记录数据的创建、修改、删除等操作历史。\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Attribute;\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 标记用户表需要审计跟踪\r\n[AuditTable]\r\npublic class User : EntityBase\r\n{\r\n    public string Username { get; set; }\r\n    public string Email { get; set; }\r\n    public string PasswordHash { get; set; }\r\n    \r\n    // EntityBase已包含审计字段：\r\n    // CreateTime, UpdateTime, CreateUserId, UpdateUserId, \r\n    // CreateUserName, UpdateUserName\r\n}\r\n\r\n// 标记订单表需要审计跟踪\r\n[AuditTable]\r\npublic class Order : EntityBase\r\n{\r\n    public string OrderNumber { get; set; }\r\n    public long UserId { get; set; }\r\n    public decimal TotalAmount { get; set; }\r\n    public DateTime OrderDate { get; set; }\r\n}\r\n\r\n// 审计拦截器示例\r\npublic class AuditInterceptor : IDbCommandInterceptor\r\n{\r\n    private readonly ICurrentUserService _currentUserService;\r\n    \r\n    public AuditInterceptor(ICurrentUserService currentUserService)\r\n    {\r\n        _currentUserService = currentUserService;\r\n    }\r\n    \r\n    public override InterceptionResult\u003cint\u003e NonQueryExecuting(\r\n        DbCommand command, \r\n        CommandEventData eventData, \r\n        InterceptionResult\u003cint\u003e result)\r\n    {\r\n        var context = eventData.Context;\r\n        var entries = context.ChangeTracker.Entries()\r\n            .Where(e =\u003e e.Entity.GetType().GetCustomAttribute\u003cAuditTableAttribute\u003e() != null)\r\n            .ToList();\r\n            \r\n        foreach (var entry in entries)\r\n        {\r\n            if (entry.Entity is IAuditableEntity auditableEntity)\r\n            {\r\n                var currentUser = _currentUserService.GetCurrentUser();\r\n                var now = DateTime.UtcNow;\r\n                \r\n                switch (entry.State)\r\n                {\r\n                    case EntityState.Added:\r\n                        auditableEntity.CreateTime = now;\r\n                        auditableEntity.UpdateTime = now;\r\n                        auditableEntity.CreateUserId = currentUser.Id;\r\n                        auditableEntity.UpdateUserId = currentUser.Id;\r\n                        auditableEntity.CreateUserName = currentUser.Username;\r\n                        auditableEntity.UpdateUserName = currentUser.Username;\r\n                        break;\r\n                        \r\n                    case EntityState.Modified:\r\n                        auditableEntity.UpdateTime = now;\r\n                        auditableEntity.UpdateUserId = currentUser.Id;\r\n                        auditableEntity.UpdateUserName = currentUser.Username;\r\n                        break;\r\n                }\r\n            }\r\n        }\r\n        \r\n        return base.NonQueryExecuting(command, eventData, result);\r\n    }\r\n}\r\n```\r\n\r\n#### 缓存表属性 (CacheTableAttribute)\r\n\r\n用于标记支持缓存策略的实体类，系统会自动对这些表的数据进行缓存管理。\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Attribute;\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 标记配置表支持缓存（配置数据变化频率低，适合缓存）\r\n[CacheTable]\r\npublic class SystemConfig : EntityBase\r\n{\r\n    public string ConfigKey { get; set; }\r\n    public string ConfigValue { get; set; }\r\n    public string Description { get; set; }\r\n    public string Category { get; set; }\r\n}\r\n\r\n// 标记字典表支持缓存（字典数据相对稳定，适合缓存）\r\n[CacheTable]\r\npublic class Dictionary : EntityBase\r\n{\r\n    public string DictType { get; set; }\r\n    public string DictKey { get; set; }\r\n    public string DictValue { get; set; }\r\n    public string Description { get; set; }\r\n    public int SortOrder { get; set; }\r\n}\r\n\r\n// 标记权限表支持缓存（权限数据访问频繁但变化不频繁）\r\n[CacheTable]\r\npublic class Permission : EntityBase\r\n{\r\n    public string PermissionCode { get; set; }\r\n    public string PermissionName { get; set; }\r\n    public string Description { get; set; }\r\n    public string Module { get; set; }\r\n}\r\n\r\n// 缓存服务示例\r\npublic class CacheService\u003cT\u003e where T : class\r\n{\r\n    private readonly IMemoryCache _memoryCache;\r\n    private readonly IDbContext _dbContext;\r\n    private readonly ILogger\u003cCacheService\u003cT\u003e\u003e _logger;\r\n    \r\n    public CacheService(IMemoryCache memoryCache, IDbContext dbContext, ILogger\u003cCacheService\u003cT\u003e\u003e logger)\r\n    {\r\n        _memoryCache = memoryCache;\r\n        _dbContext = dbContext;\r\n        _logger = logger;\r\n    }\r\n    \r\n    public async Task\u003cList\u003cT\u003e\u003e GetAllAsync()\r\n    {\r\n        var entityType = typeof(T);\r\n        var cacheAttribute = entityType.GetCustomAttribute\u003cCacheTableAttribute\u003e();\r\n        \r\n        if (cacheAttribute == null)\r\n        {\r\n            // 不支持缓存，直接从数据库查询\r\n            return await _dbContext.Set\u003cT\u003e().ToListAsync();\r\n        }\r\n        \r\n        var cacheKey = $\"CacheTable_{entityType.Name}_All\";\r\n        \r\n        if (_memoryCache.TryGetValue(cacheKey, out List\u003cT\u003e cachedData))\r\n        {\r\n            _logger.LogDebug($\"从缓存获取数据: {cacheKey}\");\r\n            return cachedData;\r\n        }\r\n        \r\n        // 从数据库查询并缓存\r\n        var data = await _dbContext.Set\u003cT\u003e().ToListAsync();\r\n        \r\n        var cacheOptions = new MemoryCacheEntryOptions\r\n        {\r\n            AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30), // 30分钟过期\r\n            SlidingExpiration = TimeSpan.FromMinutes(5), // 5分钟滑动过期\r\n            Priority = CacheItemPriority.Normal\r\n        };\r\n        \r\n        _memoryCache.Set(cacheKey, data, cacheOptions);\r\n        _logger.LogDebug($\"数据已缓存: {cacheKey}, 记录数: {data.Count}\");\r\n        \r\n        return data;\r\n    }\r\n    \r\n    public async Task InvalidateCacheAsync()\r\n    {\r\n        var entityType = typeof(T);\r\n        var cacheKey = $\"CacheTable_{entityType.Name}_All\";\r\n        \r\n        _memoryCache.Remove(cacheKey);\r\n        _logger.LogDebug($\"缓存已失效: {cacheKey}\");\r\n    }\r\n}\r\n\r\n// 缓存管理器示例\r\npublic class CacheManager\r\n{\r\n    private readonly IServiceProvider _serviceProvider;\r\n    private readonly ILogger\u003cCacheManager\u003e _logger;\r\n    \r\n    public CacheManager(IServiceProvider serviceProvider, ILogger\u003cCacheManager\u003e logger)\r\n    {\r\n        _serviceProvider = serviceProvider;\r\n        _logger = logger;\r\n    }\r\n    \r\n    public async Task RefreshAllCacheTablesAsync()\r\n    {\r\n        var assembly = Assembly.GetExecutingAssembly();\r\n        var cacheTableTypes = assembly.GetTypes()\r\n            .Where(t =\u003e t.GetCustomAttribute\u003cCacheTableAttribute\u003e() != null)\r\n            .ToList();\r\n            \r\n        foreach (var type in cacheTableTypes)\r\n        {\r\n            try\r\n            {\r\n                var serviceType = typeof(CacheService\u003c\u003e).MakeGenericType(type);\r\n                var service = _serviceProvider.GetService(serviceType);\r\n                \r\n                if (service != null)\r\n                {\r\n                    var invalidateMethod = serviceType.GetMethod(\"InvalidateCacheAsync\");\r\n                    await (Task)invalidateMethod.Invoke(service, null);\r\n                    \r\n                    var getAllMethod = serviceType.GetMethod(\"GetAllAsync\");\r\n                    await (Task)getAllMethod.Invoke(service, null);\r\n                    \r\n                    _logger.LogInformation($\"缓存表 {type.Name} 已刷新\");\r\n                }\r\n            }\r\n            catch (Exception ex)\r\n            {\r\n                _logger.LogError(ex, $\"刷新缓存表 {type.Name} 时发生错误\");\r\n            }\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n#### 软删除属性 (SoftDeleteAttribute)\r\n\r\n用于标记支持软删除功能的实体类，删除操作会将记录标记为已删除而不是物理删除。\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Attribute;\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 标记用户表支持软删除\r\n[SoftDelete]\r\npublic class User : EntityBase\r\n{\r\n    public string Username { get; set; }\r\n    public string Email { get; set; }\r\n    public string PasswordHash { get; set; }\r\n    \r\n    // EntityBase已包含IsDelete字段\r\n}\r\n\r\n// 标记文章表支持软删除\r\n[SoftDelete]\r\npublic class Article : EntityBase\r\n{\r\n    public string Title { get; set; }\r\n    public string Content { get; set; }\r\n    public long AuthorId { get; set; }\r\n    public DateTime PublishTime { get; set; }\r\n}\r\n\r\n// 软删除拦截器\r\npublic class SoftDeleteInterceptor : IDbCommandInterceptor\r\n{\r\n    public override InterceptionResult\u003cint\u003e NonQueryExecuting(\r\n        DbCommand command, \r\n        CommandEventData eventData, \r\n        InterceptionResult\u003cint\u003e result)\r\n    {\r\n        var context = eventData.Context;\r\n        \r\n        // 处理软删除实体的删除操作\r\n        var softDeleteEntries = context.ChangeTracker.Entries()\r\n            .Where(e =\u003e e.State == EntityState.Deleted \u0026\u0026 \r\n                       e.Entity.GetType().GetCustomAttribute\u003cSoftDeleteAttribute\u003e() != null)\r\n            .ToList();\r\n            \r\n        foreach (var entry in softDeleteEntries)\r\n        {\r\n            // 将删除操作转换为更新操作\r\n            entry.State = EntityState.Modified;\r\n            \r\n            if (entry.Entity is EntityBase entityBase)\r\n            {\r\n                entityBase.IsDelete = true;\r\n                entityBase.UpdateTime = DateTime.UtcNow;\r\n                // 设置更新用户信息...\r\n            }\r\n        }\r\n        \r\n        return base.NonQueryExecuting(command, eventData, result);\r\n    }\r\n}\r\n\r\n// 软删除查询过滤器\r\npublic static class SoftDeleteQueryExtensions\r\n{\r\n    public static IQueryable\u003cT\u003e WhereNotDeleted\u003cT\u003e(this IQueryable\u003cT\u003e query) \r\n        where T : class\r\n    {\r\n        var entityType = typeof(T);\r\n        var softDeleteAttribute = entityType.GetCustomAttribute\u003cSoftDeleteAttribute\u003e();\r\n        \r\n        if (softDeleteAttribute != null \u0026\u0026 typeof(EntityBase).IsAssignableFrom(entityType))\r\n        {\r\n            return query.Where(e =\u003e !((EntityBase)(object)e).IsDelete);\r\n        }\r\n        \r\n        return query;\r\n    }\r\n    \r\n    public static IQueryable\u003cT\u003e IncludeDeleted\u003cT\u003e(this IQueryable\u003cT\u003e query) \r\n        where T : class\r\n    {\r\n        // 返回包含已删除记录的查询\r\n        return query;\r\n    }\r\n    \r\n    public static IQueryable\u003cT\u003e OnlyDeleted\u003cT\u003e(this IQueryable\u003cT\u003e query) \r\n        where T : class\r\n    {\r\n        var entityType = typeof(T);\r\n        var softDeleteAttribute = entityType.GetCustomAttribute\u003cSoftDeleteAttribute\u003e();\r\n        \r\n        if (softDeleteAttribute != null \u0026\u0026 typeof(EntityBase).IsAssignableFrom(entityType))\r\n        {\r\n            return query.Where(e =\u003e ((EntityBase)(object)e).IsDelete);\r\n        }\r\n        \r\n        return query.Where(_ =\u003e false); // 如果不支持软删除，返回空结果\r\n    }\r\n}\r\n\r\n// 使用示例\r\npublic class UserService\r\n{\r\n    private readonly ApplicationDbContext _context;\r\n    \r\n    public UserService(ApplicationDbContext context)\r\n    {\r\n        _context = context;\r\n    }\r\n    \r\n    // 获取活跃用户（自动过滤已删除）\r\n    public async Task\u003cList\u003cUser\u003e\u003e GetActiveUsersAsync()\r\n    {\r\n        return await _context.Users\r\n            .WhereNotDeleted()\r\n            .ToListAsync();\r\n    }\r\n    \r\n    // 获取已删除用户\r\n    public async Task\u003cList\u003cUser\u003e\u003e GetDeletedUsersAsync()\r\n    {\r\n        return await _context.Users\r\n            .OnlyDeleted()\r\n            .ToListAsync();\r\n    }\r\n    \r\n    // 获取所有用户（包含已删除）\r\n    public async Task\u003cList\u003cUser\u003e\u003e GetAllUsersAsync()\r\n    {\r\n        return await _context.Users\r\n            .IncludeDeleted()\r\n            .ToListAsync();\r\n    }\r\n    \r\n    // 软删除用户\r\n    public async Task SoftDeleteUserAsync(long userId)\r\n    {\r\n        var user = await _context.Users.FindAsync(userId);\r\n        if (user != null)\r\n        {\r\n            _context.Users.Remove(user); // 会被拦截器转换为软删除\r\n            await _context.SaveChangesAsync();\r\n        }\r\n    }\r\n    \r\n    // 恢复已删除用户\r\n    public async Task RestoreUserAsync(long userId)\r\n    {\r\n        var user = await _context.Users\r\n            .IncludeDeleted()\r\n            .FirstOrDefaultAsync(u =\u003e u.Id == userId);\r\n            \r\n        if (user != null \u0026\u0026 user.IsDelete)\r\n        {\r\n            user.IsDelete = false;\r\n            user.UpdateTime = DateTime.UtcNow;\r\n            await _context.SaveChangesAsync();\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n#### 版本控制属性 (VersionControlAttribute)\r\n\r\n用于标记支持数据版本管理的实体类，实现乐观锁和并发控制功能。\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Attribute;\r\nusing GameFrameX.Foundation.Orm.Entity;\r\n\r\n// 标记用户表支持版本控制\r\n[VersionControl]\r\npublic class User : EntityBase\r\n{\r\n    public string Username { get; set; }\r\n    public string Email { get; set; }\r\n    public string PasswordHash { get; set; }\r\n    \r\n    // EntityBase已包含Version字段\r\n}\r\n\r\n// 标记库存表支持版本控制（防止超卖）\r\n[VersionControl]\r\npublic class Inventory : EntityBase\r\n{\r\n    public string ProductId { get; set; }\r\n    public int Quantity { get; set; }\r\n    public int ReservedQuantity { get; set; }\r\n    public decimal UnitCost { get; set; }\r\n}\r\n\r\n// 标记账户余额表支持版本控制（防止并发操作导致余额错误）\r\n[VersionControl]\r\npublic class AccountBalance : EntityBase\r\n{\r\n    public long UserId { get; set; }\r\n    public decimal Balance { get; set; }\r\n    public decimal FrozenAmount { get; set; }\r\n    public string Currency { get; set; }\r\n}\r\n\r\n// 版本控制拦截器\r\npublic class VersionControlInterceptor : IDbCommandInterceptor\r\n{\r\n    public override InterceptionResult\u003cint\u003e NonQueryExecuting(\r\n        DbCommand command, \r\n        CommandEventData eventData, \r\n        InterceptionResult\u003cint\u003e result)\r\n    {\r\n        var context = eventData.Context;\r\n        \r\n        // 处理版本控制实体的更新操作\r\n        var versionControlEntries = context.ChangeTracker.Entries()\r\n            .Where(e =\u003e e.State == EntityState.Modified \u0026\u0026 \r\n                       e.Entity.GetType().GetCustomAttribute\u003cVersionControlAttribute\u003e() != null)\r\n            .ToList();\r\n            \r\n        foreach (var entry in versionControlEntries)\r\n        {\r\n            if (entry.Entity is EntityBase entityBase)\r\n            {\r\n                // 自动递增版本号\r\n                entityBase.Version++;\r\n                \r\n                // 标记Version字段为已修改\r\n                entry.Property(nameof(EntityBase.Version)).IsModified = true;\r\n            }\r\n        }\r\n        \r\n        return base.NonQueryExecuting(command, eventData, result);\r\n    }\r\n}\r\n\r\n// 版本控制服务\r\npublic class VersionControlService\u003cT\u003e where T : EntityBase\r\n{\r\n    private readonly IDbContext _dbContext;\r\n    private readonly ILogger\u003cVersionControlService\u003cT\u003e\u003e _logger;\r\n    \r\n    public VersionControlService(IDbContext dbContext, ILogger\u003cVersionControlService\u003cT\u003e\u003e logger)\r\n    {\r\n        _dbContext = dbContext;\r\n        _logger = logger;\r\n    }\r\n    \r\n    public async Task\u003cT\u003e UpdateWithVersionCheckAsync(long id, Action\u003cT\u003e updateAction, int maxRetries = 3)\r\n    {\r\n        var entityType = typeof(T);\r\n        var versionControlAttribute = entityType.GetCustomAttribute\u003cVersionControlAttribute\u003e();\r\n        \r\n        if (versionControlAttribute == null)\r\n        {\r\n            throw new InvalidOperationException($\"实体类型 {entityType.Name} 未标记 VersionControlAttribute\");\r\n        }\r\n        \r\n        for (int attempt = 1; attempt \u003c= maxRetries; attempt++)\r\n        {\r\n            try\r\n            {\r\n                var entity = await _dbContext.Set\u003cT\u003e().FindAsync(id);\r\n                if (entity == null)\r\n                {\r\n                    throw new EntityNotFoundException($\"实体 {entityType.Name} (ID: {id}) 不存在\");\r\n                }\r\n                \r\n                var originalVersion = entity.Version;\r\n                \r\n                // 执行更新操作\r\n                updateAction(entity);\r\n                \r\n                // 设置更新时间\r\n                entity.UpdateTime = DateTime.UtcNow;\r\n                \r\n                // 保存更改\r\n                await _dbContext.SaveChangesAsync();\r\n                \r\n                _logger.LogDebug($\"实体 {entityType.Name} (ID: {id}) 更新成功，版本从 {originalVersion} 更新到 {entity.Version}\");\r\n                return entity;\r\n            }\r\n            catch (DbUpdateConcurrencyException ex)\r\n            {\r\n                _logger.LogWarning($\"实体 {entityType.Name} (ID: {id}) 版本冲突，第 {attempt} 次重试\");\r\n                \r\n                if (attempt == maxRetries)\r\n                {\r\n                    throw new ConcurrencyException($\"实体 {entityType.Name} (ID: {id}) 在 {maxRetries} 次重试后仍然存在版本冲突\", ex);\r\n                }\r\n                \r\n                // 重新加载实体以获取最新版本\r\n                _dbContext.Entry(await _dbContext.Set\u003cT\u003e().FindAsync(id)).Reload();\r\n                \r\n                // 等待一段时间后重试\r\n                await Task.Delay(TimeSpan.FromMilliseconds(100 * attempt));\r\n            }\r\n        }\r\n        \r\n        throw new InvalidOperationException(\"不应该到达这里\");\r\n    }\r\n}\r\n\r\n// 使用示例\r\npublic class InventoryService\r\n{\r\n    private readonly VersionControlService\u003cInventory\u003e _versionControlService;\r\n    private readonly ApplicationDbContext _context;\r\n    \r\n    public InventoryService(VersionControlService\u003cInventory\u003e versionControlService, ApplicationDbContext context)\r\n    {\r\n        _versionControlService = versionControlService;\r\n        _context = context;\r\n    }\r\n    \r\n    // 减少库存（防止超卖）\r\n    public async Task\u003cbool\u003e ReduceInventoryAsync(string productId, int quantity)\r\n    {\r\n        var inventory = await _context.Inventories\r\n            .FirstOrDefaultAsync(i =\u003e i.ProductId == productId);\r\n            \r\n        if (inventory == null)\r\n        {\r\n            throw new EntityNotFoundException($\"产品 {productId} 的库存记录不存在\");\r\n        }\r\n        \r\n        try\r\n        {\r\n            await _versionControlService.UpdateWithVersionCheckAsync(inventory.Id, inv =\u003e\r\n            {\r\n                if (inv.Quantity \u003c quantity)\r\n                {\r\n                    throw new InsufficientInventoryException($\"库存不足，当前库存: {inv.Quantity}，需要: {quantity}\");\r\n                }\r\n                \r\n                inv.Quantity -= quantity;\r\n            });\r\n            \r\n            return true;\r\n        }\r\n        catch (ConcurrencyException)\r\n        {\r\n            // 版本冲突，可能是并发操作导致\r\n            throw new ConcurrencyException(\"库存更新失败，请重试\");\r\n        }\r\n    }\r\n    \r\n    // 增加库存\r\n    public async Task AddInventoryAsync(string productId, int quantity)\r\n    {\r\n        var inventory = await _context.Inventories\r\n            .FirstOrDefaultAsync(i =\u003e i.ProductId == productId);\r\n            \r\n        if (inventory == null)\r\n        {\r\n            throw new EntityNotFoundException($\"产品 {productId} 的库存记录不存在\");\r\n        }\r\n        \r\n        await _versionControlService.UpdateWithVersionCheckAsync(inventory.Id, inv =\u003e\r\n        {\r\n            inv.Quantity += quantity;\r\n        });\r\n    }\r\n}\r\n\r\n// 账户余额服务示例\r\npublic class AccountBalanceService\r\n{\r\n    private readonly VersionControlService\u003cAccountBalance\u003e _versionControlService;\r\n    private readonly ApplicationDbContext _context;\r\n    \r\n    public AccountBalanceService(VersionControlService\u003cAccountBalance\u003e versionControlService, ApplicationDbContext context)\r\n    {\r\n        _versionControlService = versionControlService;\r\n        _context = context;\r\n    }\r\n    \r\n    // 扣减余额\r\n    public async Task\u003cbool\u003e DeductBalanceAsync(long userId, decimal amount, string currency = \"CNY\")\r\n    {\r\n        var balance = await _context.AccountBalances\r\n            .FirstOrDefaultAsync(b =\u003e b.UserId == userId \u0026\u0026 b.Currency == currency);\r\n            \r\n        if (balance == null)\r\n        {\r\n            throw new EntityNotFoundException($\"用户 {userId} 的 {currency} 账户不存在\");\r\n        }\r\n        \r\n        try\r\n        {\r\n            await _versionControlService.UpdateWithVersionCheckAsync(balance.Id, bal =\u003e\r\n            {\r\n                if (bal.Balance \u003c amount)\r\n                {\r\n                    throw new InsufficientBalanceException($\"余额不足，当前余额: {bal.Balance}，需要: {amount}\");\r\n                }\r\n                \r\n                bal.Balance -= amount;\r\n            });\r\n            \r\n            return true;\r\n        }\r\n        catch (ConcurrencyException)\r\n        {\r\n            throw new ConcurrencyException(\"余额更新失败，请重试\");\r\n        }\r\n    }\r\n    \r\n    // 增加余额\r\n    public async Task AddBalanceAsync(long userId, decimal amount, string currency = \"CNY\")\r\n    {\r\n        var balance = await _context.AccountBalances\r\n            .FirstOrDefaultAsync(b =\u003e b.UserId == userId \u0026\u0026 b.Currency == currency);\r\n            \r\n        if (balance == null)\r\n        {\r\n            throw new EntityNotFoundException($\"用户 {userId} 的 {currency} 账户不存在\");\r\n        }\r\n        \r\n        await _versionControlService.UpdateWithVersionCheckAsync(balance.Id, bal =\u003e\r\n        {\r\n            bal.Balance += amount;\r\n        });\r\n    }\r\n}\r\n```\r\n\r\n#### 完整集成示例\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Orm.Attribute;\r\nusing GameFrameX.Foundation.Orm.Entity;\r\nusing Microsoft.EntityFrameworkCore;\r\n\r\nnamespace MyApplication.Entities\r\n{\r\n    // 用户实体：支持审计、软删除、版本控制\r\n    [AuditTable]\r\n    [SoftDelete]\r\n    [VersionControl]\r\n    public class User : EntityBase\r\n    {\r\n        public string Username { get; set; }\r\n        public string Email { get; set; }\r\n        public string PasswordHash { get; set; }\r\n        public string FirstName { get; set; }\r\n        public string LastName { get; set; }\r\n        public DateTime? LastLoginTime { get; set; }\r\n    }\r\n    \r\n    // 系统配置：支持缓存、审计\r\n    [CacheTable]\r\n    [AuditTable]\r\n    public class SystemConfig : EntityBase\r\n    {\r\n        public string ConfigKey { get; set; }\r\n        public string ConfigValue { get; set; }\r\n        public string Description { get; set; }\r\n        public string Category { get; set; }\r\n    }\r\n    \r\n    // 库存记录：支持版本控制、审计\r\n    [VersionControl]\r\n    [AuditTable]\r\n    public class Inventory : EntityBase\r\n    {\r\n        public string ProductId { get; set; }\r\n        public int Quantity { get; set; }\r\n        public int ReservedQuantity { get; set; }\r\n        public decimal UnitCost { get; set; }\r\n        public string WarehouseCode { get; set; }\r\n    }\r\n    \r\n    // 订单记录：支持审计、软删除\r\n    [AuditTable]\r\n    [SoftDelete]\r\n    public class Order : EntityBase\r\n    {\r\n        public string OrderNumber { get; set; }\r\n        public long UserId { get; set; }\r\n        public decimal TotalAmount { get; set; }\r\n        public DateTime OrderDate { get; set; }\r\n        public OrderStatus Status { get; set; }\r\n        \r\n        public virtual User User { get; set; }\r\n        public virtual ICollection\u003cOrderItem\u003e OrderItems { get; set; }\r\n    }\r\n}\r\n\r\n// DbContext配置\r\npublic class ApplicationDbContext : DbContext\r\n{\r\n    public DbSet\u003cUser\u003e Users { get; set; }\r\n    public DbSet\u003cSystemConfig\u003e SystemConfigs { get; set; }\r\n    public DbSet\u003cInventory\u003e Inventories { get; set; }\r\n    public DbSet\u003cOrder\u003e Orders { get; set; }\r\n    \r\n    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)\r\n    {\r\n        optionsBuilder\r\n            .AddInterceptors(\r\n                new AuditInterceptor(),\r\n                new SoftDeleteInterceptor(),\r\n                new VersionControlInterceptor()\r\n            );\r\n    }\r\n    \r\n    protected override void OnModelCreating(ModelBuilder modelBuilder)\r\n    {\r\n        // 为所有标记了SoftDeleteAttribute的实体添加全局查询过滤器\r\n        foreach (var entityType in modelBuilder.Model.GetEntityTypes())\r\n        {\r\n            var clrType = entityType.ClrType;\r\n            if (clrType.GetCustomAttribute\u003cSoftDeleteAttribute\u003e() != null \u0026\u0026\r\n                typeof(EntityBase).IsAssignableFrom(clrType))\r\n            {\r\n                var parameter = Expression.Parameter(clrType, \"e\");\r\n                var property = Expression.Property(parameter, nameof(EntityBase.IsDelete));\r\n                var condition = Expression.Equal(property, Expression.Constant(false));\r\n                var lambda = Expression.Lambda(condition, parameter);\r\n                \r\n                modelBuilder.Entity(clrType).HasQueryFilter(lambda);\r\n            }\r\n        }\r\n        \r\n        base.OnModelCreating(modelBuilder);\r\n    }\r\n}\r\n\r\n// 服务注册\r\npublic void ConfigureServices(IServiceCollection services)\r\n{\r\n    services.AddDbContext\u003cApplicationDbContext\u003e(options =\u003e\r\n        options.UseSqlServer(connectionString));\r\n    \r\n    services.AddScoped\u003cAuditInterceptor\u003e();\r\n    services.AddScoped\u003cSoftDeleteInterceptor\u003e();\r\n    services.AddScoped\u003cVersionControlInterceptor\u003e();\r\n    \r\n    services.AddScoped(typeof(CacheService\u003c\u003e));\r\n    services.AddScoped(typeof(VersionControlService\u003c\u003e));\r\n    services.AddScoped\u003cCacheManager\u003e();\r\n    \r\n    services.AddMemoryCache();\r\n}\r\n```\r\n\r\n### 🖊️ 日志工具库 (GameFrameX.Foundation.Logger)\r\n\r\n基于 Serilog 的日志配置工具，提供简单易用的日志记录功能。\r\n\r\n#### 特性\r\n\r\n- 支持多种日志级别 (Debug, Info, Warning, Error, Fatal)\r\n- 灵活的输出配置\r\n- 支持自定义日志提供程序\r\n- 提供日志自我诊断\r\n- ✅ **预初始化日志支持**: 无需手动初始化，直接使用 LogHelper 即可输出日志\r\n- ✅ **日志自动合并**: 初始化前后的日志会自动合并到正式日志系统\r\n\r\n#### 预初始化日志功能\r\n\r\n在正式日志系统初始化之前，可以直接使用 LogHelper 输出日志到控制台。当调用 `LogHandler.Create()` 初始化正式日志后，之前的临时日志会自动合并到新日志系统中，确保日志不丢失。\r\n\r\n```csharp\r\nclass Program\r\n{\r\n    static void Main(string[] args)\r\n    {\r\n        // 无需任何初始化，直接使用 LogHelper\r\n        LogHelper.Info(\"正在加载配置...\");\r\n        LogHelper.Debug(\"参数: {Args}\", string.Join(\", \", args));\r\n        LogHelper.Warning(\"配置不存在，使用默认值\");\r\n\r\n        // 初始化正式日志系统\r\n        var logger = LogHandler.Create(options);\r\n\r\n        // 之前的临时日志已自动合并到新日志\r\n        LogHelper.Info(\"系统启动完成\");\r\n    }\r\n}\r\n```\r\n\r\n#### 使用示例\r\n\r\n```csharp\r\n// 初始化日志\r\nLogHandler.Create(LogOptions.Default);\r\n\r\n// 记录日志\r\nLogHelper.Debug(\"调试信息\");\r\nLogHelper.Info(\"普通信息\");\r\nLogHelper.Warning(\"警告信息\");\r\nLogHelper.Error(\"错误信息\");\r\nLogHelper.Fatal(\"致命错误\");\r\n```\r\n\r\n### ⚙️ 命令行参数处理 (GameFrameX.Foundation.Options)\r\n\r\n一个强大的命令行参数和环境变量解析库，支持将命令行参数和环境变量自动映射到强类型配置对象。\r\n\r\n#### 特性\r\n\r\n- ✅ **参数优先级处理**: 命令行参数 \u003e 环境变量 \u003e 默认值\r\n- ✅ **泛型支持**: 支持任意强类型配置类\r\n- ✅ **多种启动方式兼容**: 支持Docker、exe、shell等启动方式\r\n- ✅ **自动前缀处理**: 自动为参数添加`--`前缀\r\n- ✅ **布尔参数支持**: 支持多种布尔参数格式\r\n- ✅ **环境变量映射**: 自动映射环境变量到配置属性\r\n- ✅ **类型转换**: 自动转换字符串参数到目标类型\r\n- ✅ **特性支持**: 支持丰富的配置特性\r\n\r\n#### 核心组件\r\n\r\n| 组件                             | 功能描述                 |\r\n|--------------------------------|----------------------|\r\n| `CommandLineArgumentConverter` | 命令行参数转换器，提供参数处理的核心功能 |\r\n| `OptionsBuilder\u003cT\u003e`            | 配置构建器，用于构建泛型配置对象     |\r\n| `OptionsProvider`              | 配置提供器，用于获取和管理配置对象    |\r\n\r\n#### 快速开始\r\n\r\n##### 1. 定义配置类\r\n\r\n```csharp\r\npublic class AppConfig\r\n{\r\n    public string Host { get; set; } = \"localhost\";\r\n    public int Port { get; set; } = 8080;\r\n    public bool Debug { get; set; } = false;\r\n    public string LogLevel { get; set; } = \"info\";\r\n    public double Timeout { get; set; } = 30.5;\r\n}\r\n```\r\n\r\n##### 2. 使用OptionsBuilder\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Options;\r\n\r\nclass Program\r\n{\r\n    static void Main(string[] args)\r\n    {\r\n        // 创建选项构建器\r\n        var builder = new OptionsBuilder\u003cAppConfig\u003e(args);\r\n        \r\n        // 构建配置对象\r\n        var config = builder.Build();\r\n        \r\n        // 使用配置\r\n        Console.WriteLine($\"服务器: {config.Host}:{config.Port}\");\r\n        Console.WriteLine($\"调试模式: {config.Debug}\");\r\n        Console.WriteLine($\"日志级别: {config.LogLevel}\");\r\n        Console.WriteLine($\"超时时间: {config.Timeout}秒\");\r\n    }\r\n}\r\n```\r\n\r\n#### 使用方式\r\n\r\n##### 命令行参数\r\n\r\n支持多种参数格式：\r\n\r\n```bash\r\n# 键值对格式\r\nmyapp.exe --host=example.com --port=9090 --debug=true\r\n\r\n# 分离格式\r\nmyapp.exe --host example.com --port 9090 --debug true\r\n\r\n# 布尔标志格式\r\nmyapp.exe --host example.com --port 9090 --debug\r\n\r\n# 混合格式\r\nmyapp.exe --host=example.com --port 9090 --debug\r\n```\r\n\r\n##### 环境变量\r\n\r\n```bash\r\n# 设置环境变量\r\nexport HOST=example.com\r\nexport PORT=9090\r\nexport DEBUG=true\r\n\r\n# 运行程序\r\nmyapp.exe\r\n```\r\n\r\n##### Docker支持\r\n\r\n```dockerfile\r\n# Dockerfile\r\nFROM mcr.microsoft.com/dotnet/runtime:8.0\r\nCOPY . /app\r\nWORKDIR /app\r\nENTRYPOINT [\"dotnet\", \"MyApp.dll\"]\r\n```\r\n\r\n```bash\r\n# Docker运行\r\ndocker run myapp --host example.com --port 9090 --debug\r\n\r\n# 或使用环境变量\r\ndocker run -e HOST=example.com -e PORT=9090 -e DEBUG=true myapp\r\n```\r\n\r\n#### 高级特性\r\n\r\n##### 使用特性配置\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Options.Attributes;\r\n\r\npublic class AdvancedConfig\r\n{\r\n    [Option(\"h\", \"host\", Required = false, DefaultValue = \"localhost\")]\r\n    [HelpText(\"服务器主机地址\")]\r\n    public string Host { get; set; }\r\n\r\n    [Option(\"p\", \"port\", Required = true)]\r\n    [HelpText(\"服务器端口号\")]\r\n    public int Port { get; set; }\r\n\r\n    [FlagOption(\"d\", \"debug\")]\r\n    [HelpText(\"启用调试模式\")]\r\n    public bool Debug { get; set; }\r\n\r\n    [RequiredOption(\"api-key\", Required = true)]\r\n    [EnvironmentVariable(\"API_KEY\")]\r\n    [HelpText(\"API密钥\")]\r\n    public string ApiKey { get; set; }\r\n\r\n    [DefaultValue(30.0)]\r\n    public double Timeout { get; set; }\r\n}\r\n```\r\n\r\n##### 构建器选项\r\n\r\n```csharp\r\nvar builder = new OptionsBuilder\u003cAppConfig\u003e(\r\n    args: args,\r\n    boolFormat: BoolArgumentFormat.Flag,        // 布尔参数格式\r\n    ensurePrefixedKeys: true,                   // 确保参数有前缀\r\n    useEnvironmentVariables: true              // 使用环境变量\r\n);\r\n\r\nvar config = builder.Build(skipValidation: false); // 是否跳过验证\r\n```\r\n\r\n#### 参数优先级\r\n\r\n参数按以下优先级应用（高优先级覆盖低优先级）：\r\n\r\n1. **命令行参数** (最高优先级)\r\n2. **环境变量**\r\n3. **默认值** (最低优先级)\r\n\r\n##### 示例\r\n\r\n```csharp\r\npublic class Config\r\n{\r\n    public string Host { get; set; } = \"localhost\";  // 默认值\r\n    public int Port { get; set; } = 8080;           // 默认值\r\n}\r\n```\r\n\r\n```bash\r\n# 设置环境变量\r\nexport HOST=env.example.com\r\nexport PORT=7070\r\n\r\n# 运行程序（命令行参数覆盖环境变量）\r\nmyapp.exe --host cmd.example.com\r\n\r\n# 结果：\r\n# Host = \"cmd.example.com\"  (来自命令行参数)\r\n# Port = 7070               (来自环境变量)\r\n```\r\n\r\n#### 布尔参数处理\r\n\r\n支持多种布尔参数格式：\r\n\r\n```bash\r\n# 标志格式（推荐）\r\nmyapp.exe --debug                    # debug = true\r\n\r\n# 键值对格式\r\nmyapp.exe --debug=true               # debug = true\r\nmyapp.exe --debug=false              # debug = false\r\n\r\n# 分离格式\r\nmyapp.exe --debug true               # debug = true\r\nmyapp.exe --debug false              # debug = false\r\n\r\n# 支持的布尔值\r\ntrue, false, 1, 0, yes, no, on, off\r\n```\r\n\r\n#### 类型转换\r\n\r\n自动支持以下类型转换：\r\n\r\n- `string` - 直接使用\r\n- `int`, `int?` - 整数转换\r\n- `bool`, `bool?` - 布尔值转换\r\n- `double`, `double?` - 双精度浮点数转换\r\n- `float`, `float?` - 单精度浮点数转换\r\n- `decimal`, `decimal?` - 十进制数转换\r\n- `DateTime`, `DateTime?` - 日期时间转换\r\n- `Guid`, `Guid?` - GUID转换\r\n- `Enum` - 枚举转换\r\n\r\n##### 示例\r\n\r\n```csharp\r\npublic class TypedConfig\r\n{\r\n    public int Port { get; set; }\r\n    public bool Debug { get; set; }\r\n    public DateTime StartTime { get; set; }\r\n    public LogLevel Level { get; set; }  // 枚举\r\n}\r\n\r\npublic enum LogLevel\r\n{\r\n    Debug, Info, Warning, Error\r\n}\r\n```\r\n\r\n```bash\r\nmyapp.exe --port 9090 --debug true --start-time \"2024-01-01 10:00:00\" --level Info\r\n```\r\n\r\n#### 错误处理\r\n\r\n##### 必需参数验证\r\n\r\n```csharp\r\npublic class Config\r\n{\r\n    [RequiredOption(\"api-key\", Required = true)]\r\n    public string ApiKey { get; set; }\r\n}\r\n```\r\n\r\n如果缺少必需参数，会抛出 `ArgumentException`：\r\n\r\n```\r\n缺少必需的选项: api-key\r\n```\r\n\r\n##### 类型转换错误\r\n\r\n当参数值无法转换为目标类型时，会使用默认值并在控制台输出警告信息。\r\n\r\n#### 最佳实践\r\n\r\n##### 1. 配置类设计\r\n\r\n```csharp\r\npublic class AppConfig\r\n{\r\n    // 使用有意义的默认值\r\n    public string Host { get; set; } = \"localhost\";\r\n    public int Port { get; set; } = 8080;\r\n    \r\n    // 布尔属性默认为false\r\n    public bool Debug { get; set; } = false;\r\n    \r\n    // 使用特性提供更多信息\r\n    [RequiredOption(\"database-url\", Required = true)]\r\n    [EnvironmentVariable(\"DATABASE_URL\")]\r\n    public string DatabaseUrl { get; set; }\r\n}\r\n```\r\n\r\n##### 2. 错误处理\r\n\r\n```csharp\r\ntry\r\n{\r\n    var builder = new OptionsBuilder\u003cAppConfig\u003e(args);\r\n    var config = builder.Build();\r\n    \r\n    // 使用配置启动应用\r\n    StartApplication(config);\r\n}\r\ncatch (ArgumentException ex)\r\n{\r\n    Console.WriteLine($\"配置错误: {ex.Message}\");\r\n    Environment.Exit(1);\r\n}\r\n```\r\n\r\n##### 3. Docker集成\r\n\r\n```csharp\r\n// Program.cs\r\npublic class Program\r\n{\r\n    public static void Main(string[] args)\r\n    {\r\n        var builder = new OptionsBuilder\u003cAppConfig\u003e(args);\r\n        var config = builder.Build();\r\n        \r\n        // 在Docker中，通常使用环境变量\r\n        // 在开发中，通常使用命令行参数\r\n        \r\n        var app = CreateApplication(config);\r\n        app.Run();\r\n    }\r\n}\r\n```\r\n\r\n```yaml\r\n# docker-compose.yml\r\nversion: '3.8'\r\nservices:\r\n  myapp:\r\n    image: myapp:latest\r\n    environment:\r\n      - HOST=0.0.0.0\r\n      - PORT=8080\r\n      - DEBUG=false\r\n    command: [ \"--log-level\", \"info\" ]\r\n```\r\n\r\n#### 完整示例\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Options;\r\nusing GameFrameX.Foundation.Options.Attributes;\r\n\r\nnamespace MyApp\r\n{\r\n    public class ServerConfig\r\n    {\r\n        [Option(\"h\", \"host\", DefaultValue = \"localhost\")]\r\n        [EnvironmentVariable(\"SERVER_HOST\")]\r\n        [HelpText(\"服务器主机地址\")]\r\n        public string Host { get; set; }\r\n\r\n        [Option(\"p\", \"port\", DefaultValue = 8080)]\r\n        [EnvironmentVariable(\"SERVER_PORT\")]\r\n        [HelpText(\"服务器端口号\")]\r\n        public int Port { get; set; }\r\n\r\n        [FlagOption(\"d\", \"debug\")]\r\n        [EnvironmentVariable(\"DEBUG\")]\r\n        [HelpText(\"启用调试模式\")]\r\n        public bool Debug { get; set; }\r\n\r\n        [RequiredOption(\"database-url\", Required = true)]\r\n        [EnvironmentVariable(\"DATABASE_URL\")]\r\n        [HelpText(\"数据库连接字符串\")]\r\n        public string DatabaseUrl { get; set; }\r\n\r\n        [Option(\"timeout\", DefaultValue = 30.0)]\r\n        [EnvironmentVariable(\"REQUEST_TIMEOUT\")]\r\n        [HelpText(\"请求超时时间（秒）\")]\r\n        public double Timeout { get; set; }\r\n    }\r\n\r\n    class Program\r\n    {\r\n        static void Main(string[] args)\r\n        {\r\n            try\r\n            {\r\n                var builder = new OptionsBuilder\u003cServerConfig\u003e(args);\r\n                var config = builder.Build();\r\n\r\n                Console.WriteLine(\"服务器配置:\");\r\n                Console.WriteLine($\"  主机: {config.Host}\");\r\n                Console.WriteLine($\"  端口: {config.Port}\");\r\n                Console.WriteLine($\"  调试: {config.Debug}\");\r\n                Console.WriteLine($\"  数据库: {config.DatabaseUrl}\");\r\n                Console.WriteLine($\"  超时: {config.Timeout}秒\");\r\n\r\n                // 启动服务器\r\n                StartServer(config);\r\n            }\r\n            catch (ArgumentException ex)\r\n            {\r\n                Console.WriteLine($\"配置错误: {ex.Message}\");\r\n                ShowHelp();\r\n                Environment.Exit(1);\r\n            }\r\n        }\r\n\r\n        static void StartServer(ServerConfig config)\r\n        {\r\n            // 服务器启动逻辑\r\n            Console.WriteLine($\"服务器启动在 {config.Host}:{config.Port}\");\r\n        }\r\n\r\n        static void ShowHelp()\r\n        {\r\n            Console.WriteLine(\"用法:\");\r\n            Console.WriteLine(\"  myapp.exe --host \u003c主机\u003e --port \u003c端口\u003e --database-url \u003c数据库URL\u003e [选项]\");\r\n            Console.WriteLine();\r\n            Console.WriteLine(\"选项:\");\r\n            Console.WriteLine(\"  -h, --host \u003c主机\u003e           服务器主机地址 (默认: localhost)\");\r\n            Console.WriteLine(\"  -p, --port \u003c端口\u003e           服务器端口号 (默认: 8080)\");\r\n            Console.WriteLine(\"  -d, --debug                 启用调试模式\");\r\n            Console.WriteLine(\"      --database-url \u003cURL\u003e    数据库连接字符串 (必需)\");\r\n            Console.WriteLine(\"      --timeout \u003c秒\u003e          请求超时时间 (默认: 30.0)\");\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n#### CommandLineArgumentConverter 使用\r\n\r\n除了 OptionsBuilder 之外，您也可以直接使用底层的 CommandLineArgumentConverter：\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Options;\r\n\r\n// 创建转换器实例\r\nvar converter = new CommandLineArgumentConverter();\r\n\r\n// 原始命令行参数\r\nvar args = new[] { \"--port\", \"8080\", \"-h\", \"localhost\" };\r\n\r\n// 设置环境变量（可选）\r\nEnvironment.SetEnvironmentVariable(\"APP_NAME\", \"MyApplication\");\r\nEnvironment.SetEnvironmentVariable(\"LOG_LEVEL\", \"debug-mode\");\r\n\r\n// 转换为标准格式（合并命令行参数和环境变量）\r\nvar standardArgs = converter.ConvertToStandardFormat(args);\r\n// 结果: [\"--port\", \"8080\", \"-h\", \"localhost\", \"--APP_NAME\", \"MyApplication\", \"--LOG_LEVEL\", \"debugmode\"]\r\n\r\n// 转换为命令行字符串\r\nvar commandLineString = converter.ToCommandLineString(standardArgs);\r\n// 结果: \"--port 8080 -h localhost --APP_NAME MyApplication --LOG_LEVEL debugmode\"\r\n\r\n// 获取所有环境变量\r\nvar envVars = converter.GetEnvironmentVariables();\r\nConsole.WriteLine($\"检测到 {envVars.Count} 个环境变量\");\r\n```\r\n\r\n##### 布尔类型参数支持\r\n\r\n`CommandLineArgumentConverter` 支持智能识别和处理布尔类型参数，提供三种格式：\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Options;\r\n\r\n// 设置布尔类型环境变量\r\nEnvironment.SetEnvironmentVariable(\"ENABLE_LOGGING\", \"true\");\r\nEnvironment.SetEnvironmentVariable(\"DEBUG_MODE\", \"false\");\r\nEnvironment.SetEnvironmentVariable(\"VERBOSE\", \"yes\");\r\n\r\nvar converter = new CommandLineArgumentConverter();\r\n\r\n// 1. 标志格式 (默认) - 只为 true 值添加标志\r\nconverter.BoolFormat = BoolArgumentFormat.Flag;\r\nvar flagArgs = converter.ConvertToStandardFormat(Array.Empty\u003cstring\u003e());\r\n// 结果: [\"--ENABLE_LOGGING\", \"--VERBOSE\"] (只包含 true 值)\r\n\r\n// 2. 键值对格式 - 添加键值对\r\nconverter.BoolFormat = BoolArgumentFormat.KeyValue;\r\nvar keyValueArgs = converter.ConvertToStandardFormat(Array.Empty\u003cstring\u003e());\r\n// 结果: [\"--ENABLE_LOGGING\", \"true\", \"--DEBUG_MODE\", \"false\", \"--VERBOSE\", \"true\"]\r\n\r\n// 3. 分离格式 - 键和值分开\r\nconverter.BoolFormat = BoolArgumentFormat.Separated;\r\nvar separatedArgs = converter.ConvertToStandardFormat(Array.Empty\u003cstring\u003e());\r\n// 结果: [\"--ENABLE_LOGGING\", \"true\", \"--DEBUG_MODE\", \"false\", \"--VERBOSE\", \"true\"]\r\n```\r\n\r\n支持的布尔值格式：\r\n\r\n- **True 值**: `\"true\"`, `\"1\"`, `\"yes\"`, `\"on\"`, `\"enabled\"` (不区分大小写)\r\n- **False 值**: `\"false\"`, `\"0\"`, `\"no\"`, `\"off\"`, `\"disabled\"` (不区分大小写)\r\n\r\n### 🛠️ 通用工具类 (GameFrameX.Foundation.Utility)\r\n\r\n提供一系列实用的工具类，包含控制台操作、环境管理、时间处理和雪花ID生成等功能。\r\n\r\n#### 核心组件概览\r\n\r\n| 组件        | 文件名                    | 主要功能                      |\r\n|-----------|------------------------|---------------------------|\r\n| **控制台助手** | `ConsoleHelper.cs`     | 控制台Logo打印和格式化输出           |\r\n| **环境助手**  | `EnvironmentHelper.cs` | 环境变量管理和环境类型定义             |\r\n| **时间助手**  | `TimerHelper.cs`       | Unix时间戳处理和时间转换            |\r\n| **雪花ID**  | `SnowFlakeIdHelper.cs` | 分布式唯一ID生成器（Snowflake算法实现） |\r\n\r\n#### 控制台助手功能\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility;\r\n\r\n// 打印应用程序Logo\r\nConsoleHelper.PrintLogo();\r\n// 输出格式化的控制台Logo，用于应用程序启动时的品牌展示\r\n```\r\n\r\n#### 环境管理功能\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility;\r\n\r\n// 获取当前环境类型\r\nstring currentEnv = Environments.Development;\r\nConsole.WriteLine($\"当前环境: {currentEnv}\");\r\n\r\n// 环境判断\r\nif (Environment.GetEnvironmentVariable(\"ASPNETCORE_ENVIRONMENT\") == Environments.Development)\r\n{\r\n    // 开发环境特定逻辑\r\n    Console.WriteLine(\"运行在开发环境\");\r\n}\r\n```\r\n\r\n#### 时间处理功能\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility;\r\n\r\n// Unix时间戳常量\r\nDateTime epochLocal = TimerHelper.EpochLocal;   // 本地时区的Unix纪元时间\r\nDateTime epochUtc = TimerHelper.EpochUtc;       // UTC时区的Unix纪元时间\r\n\r\n// 获取当前Unix时间戳（秒）\r\nlong unixSeconds = TimerHelper.UnixTimeSeconds();\r\nConsole.WriteLine($\"当前Unix时间戳（秒）: {unixSeconds}\");\r\n\r\n// 获取当前Unix时间戳（毫秒）\r\nlong unixMilliseconds = TimerHelper.UnixTimeMilliseconds();\r\nConsole.WriteLine($\"当前Unix时间戳（毫秒）: {unixMilliseconds}\");\r\n\r\n// 时间戳转换示例\r\nDateTime currentTime = DateTime.UtcNow;\r\nlong timestamp = ((DateTimeOffset)currentTime).ToUnixTimeSeconds();\r\nDateTime restored = DateTimeOffset.FromUnixTimeSeconds(timestamp).DateTime;\r\n```\r\n\r\n#### 雪花ID生成器\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility;\r\n\r\n// 使用默认配置生成ID\r\nlong id1 = SnowFlakeIdHelper.GenerateId();\r\nlong id2 = SnowFlakeIdHelper.GenerateId();\r\nConsole.WriteLine($\"生成的ID: {id1}, {id2}\");\r\n\r\n// 配置工作节点ID和数据中心ID\r\nSnowFlakeIdHelper.WorkId = 1;        // 工作节点ID (0-31)\r\nSnowFlakeIdHelper.DataCenterId = 1;  // 数据中心ID (0-31)\r\n\r\n// 生成配置后的ID\r\nlong configuredId = SnowFlakeIdHelper.GenerateId();\r\nConsole.WriteLine($\"配置后的ID: {configuredId}\");\r\n\r\n// 获取时间戳相关信息\r\nDateTime utcStart = SnowFlakeIdHelper.UtcTimeStart;  // UTC起始时间\r\nlong epochTime = SnowFlakeIdHelper.EpochTime;        // 纪元时间戳\r\n\r\nConsole.WriteLine($\"雪花ID起始时间: {utcStart}\");\r\nConsole.WriteLine($\"纪元时间戳: {epochTime}\");\r\n```\r\n\r\n##### 雪花ID算法说明\r\n\r\n雪花ID（Snowflake）是Twitter开源的分布式ID生成算法，具有以下特点：\r\n\r\n- **全局唯一**: 在分布式环境中保证ID的全局唯一性\r\n- **趋势递增**: 生成的ID大致按时间递增，有利于数据库索引\r\n- **高性能**: 单机每秒可生成数百万个ID\r\n- **无依赖**: 不依赖数据库或其他外部系统\r\n\r\nID结构（64位）：\r\n\r\n```\r\n0 - 0000000000 0000000000 0000000000 0000000000 0 - 00000 - 00000 - 000000000000\r\n|   |                                             |   |       |       |\r\n|   |\u003c-------------- 41位时间戳 ----------------\u003e|   |\u003c-5位-\u003e|\u003c-5位-\u003e|\u003c--12位--\u003e\r\n|                                                 |           |       |\r\n符号位(1位)                                        |      数据中心ID   序列号\r\n                                                  |      (5位)      (12位)\r\n                                               工作节点ID\r\n                                                (5位)\r\n```\r\n\r\n- **1位符号位**: 固定为0\r\n- **41位时间戳**: 精确到毫秒，可使用约69年\r\n- **5位数据中心ID**: 支持32个数据中心\r\n- **5位工作节点ID**: 每个数据中心支持32个工作节点\r\n- **12位序列号**: 同一毫秒内支持4096个ID\r\n\r\n#### 完整使用示例\r\n\r\n```csharp\r\nusing GameFrameX.Foundation.Utility;\r\n\r\nnamespace MyApplication\r\n{\r\n    class Program\r\n    {\r\n        static void Main(string[] args)\r\n        {\r\n            // 打印应用程序Logo\r\n            ConsoleHelper.PrintLogo();\r\n            \r\n            // 检查运行环境\r\n            string env = Environment.GetEnvironmentVariable(\"ASPNETCORE_ENVIRONMENT\") ?? Environments.Development;\r\n            Console.WriteLine($\"当前运行环境: {env}\");\r\n            \r\n            // 配置雪花ID生成器\r\n            SnowFlakeIdHelper.WorkId = 1;\r\n            SnowFlakeIdHelper.DataCenterId = 1;\r\n            \r\n            // 生成唯一ID\r\n            for (int i = 0; i \u003c 5; i++)\r\n            {\r\n                long id = SnowFlakeIdHelper.GenerateId();\r\n                long timestamp = TimerHelper.UnixTimeMilliseconds();\r\n                \r\n                Console.WriteLine($\"ID: {id}, 时间戳: {timestamp}\");\r\n                \r\n                // 短暂延迟以观察ID变化\r\n                Thread.Sleep(1);\r\n            }\r\n            \r\n            // 时间处理示例\r\n            Console.WriteLine($\"Unix纪元时间(UTC): {TimerHelper.EpochUtc}\");\r\n            Console.WriteLine($\"Unix纪元时间(本地): {TimerHelper.EpochLocal}\");\r\n            Console.WriteLine($\"当前Unix时间戳(秒): {TimerHelper.UnixTimeSeconds()}\");\r\n            Console.WriteLine($\"当前Unix时间戳(毫秒): {TimerHelper.UnixTimeMilliseconds()}\");\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n## 🧪 测试\r\n\r\n项目包含完整的单元测试，确保代码质量和功能正确性。所有核心功能都有对应的测试用例，测试覆盖率达到95%以上。\r\n\r\n### 测试覆盖范围\r\n\r\n#### 🧩 扩展方法库测试 (Extensions)\r\n\r\n- **ArgumentAlreadyExceptionTests**: 参数已存在异常测试\r\n- **BidirectionalDictionaryTests**: 双向字典功能测试\r\n- **ByteExtensionTests**: 字节数组扩展方法测试\r\n- **CollectionExtensionsTests**: 集合扩展方法测试\r\n- **ConcurrentLimitedQueueTests**: 并发限制队列测试\r\n- **DisposableConcurrentDictionaryTests**: 可释放并发字典测试\r\n- **DisposableDictionaryTests**: 可释放字典测试\r\n- **IDictionaryExtensionsTests**: 字典扩展方法测试\r\n- **IEnumerableExtensionsTests**: 枚举扩展方法测试\r\n- **ListExtensionsTests**: 列表扩展方法测试\r\n- **LookupXTests**: 查找表功能测试\r\n- **NullObjectTests**: 空对象模式测试\r\n- **NullableConcurrentDictionaryTests**: 可空并发字典测试\r\n- **NullableDictionaryTests**: 可空字典测试\r\n- **ObjectExtensionsTests**: 对象扩展方法测试\r\n- **ReadOnlySpanExtensionsTests**: 只读Span扩展测试\r\n- **SequenceReaderExtensionsTests**: 序列读取器扩展测试\r\n- **SpanExtensionsTests**: Span扩展方法测试\r\n- **StringExtensionsTests**: 字符串扩展方法测试\r\n- **TypeExtensionsTests**: 类型扩展方法测试\r\n\r\n#### 🔐 加密工具库测试 (Encryption)\r\n\r\n- **AesHelperTests**: AES加密算法测试\r\n- **DsaHelperTests**: DSA数字签名测试\r\n- **RsaHelperTests**: RSA加密算法测试\r\n- **Sm2HelperTests**: SM2国密算法测试\r\n- **Sm4HelperTests**: SM4国密算法测试\r\n- **XorHelperTests**: XOR异或加密测试\r\n\r\n#### 🌐 本地化框架测试 (Localization)\r\n\r\n- **LocalizationServiceTests**: 本地化服务核心功能测试\r\n    - 单例模式验证测试\r\n    - 本地化字符串获取测试\r\n    - 参数化消息格式化测试\r\n    - 未知键处理测试\r\n    - 线程安全并发测试\r\n- **ResourceManagerTests**: 资源管理器测试\r\n    - 提供者优先级测试\r\n    - 懒加载机制测试\r\n    - 统计信息验证测试\r\n- **DefaultResourceProviderTests**: 默认资源提供者测试\r\n- **AssemblyResourceProviderTests**: 程序集资源提供者测试\r\n    - .resx文件加载测试\r\n    - 多文化支持测试\r\n    - 资源缓存机制测试\r\n\r\n#### 🔗 哈希工具库测试 (Hash)\r\n\r\n- **CrcHelperTests**: CRC校验算法测试\r\n- **HmacSha256HelperTests**: HMAC-SHA256测试\r\n- **Md5HelperTests**: MD5哈希算法测试\r\n- **MurmurHash3HelperTests**: MurmurHash3算法测试\r\n- **Sha1HelperTests**: SHA-1哈希算法测试\r\n- **Sha256HelperTests**: SHA-256哈希算法测试\r\n- **Sha512HelperTests**: SHA-512哈希算法测试\r\n- **XxHashHelperTests**: xxHash高性能哈希测试\r\n\r\n#### 🌐 HTTP工具库测试 (Http.Extension)\r\n\r\n- **HttpExtensionTests**: HTTP客户端扩展方法测试\r\n\r\n#### ⚙️ 命令行参数处理测试 (Options)\r\n\r\n- **CommandLineArgumentConverterTests**: 命令行参数转换器功能测试\r\n    - 空参数数组处理测试\r\n    - 空参数值处理测试\r\n    - 重复参数检测测试\r\n    - 环境变量转换测试\r\n    - 值清理功能测试\r\n    - 单连字符参数转换测试\r\n    - 命令行字符串生成测试\r\n    - 环境变量获取测试\r\n    - 完整工作流程测试\r\n    - 布尔类型参数处理测试\r\n        - 标志格式布尔参数测试\r\n        - 键值对格式布尔参数测试\r\n        - 分离格式布尔参数测试\r\n        - 多种布尔值格式解析测试\r\n        - 非布尔值处理测试\r\n- **OptionsBuilderTests**: 选项构建器功能测试\r\n    - 基本配置构建测试\r\n    - 特性配置测试\r\n    - 类型转换测试\r\n    - 验证功能测试\r\n- **OptionsProviderTests**: 选项提供器功能测试\r\n    - 配置注册和获取测试\r\n    - 全局配置管理测试\r\n\r\n### 运行测试\r\n\r\n```bash\r\n# 运行所有测试\r\ndotnet test\r\n\r\n# 运行特定模块测试\r\ndotnet test --filter \"FullyQualifiedName~Extensions\"\r\ndotnet test --filter \"FullyQualifiedName~Encryption\"\r\ndotnet test --filter \"FullyQualifiedName~Hash\"\r\ndotnet test --filter \"FullyQualifiedName~Localization\"\r\ndotnet test --filter \"FullyQualifiedName~Options\"\r\n\r\n# 运行特定测试类\r\ndotnet test --filter \"ClassName=XxHashHelperTests\"\r\ndotnet test --filter \"ClassName=StringExtensionsTests\"\r\ndotnet test --filter \"ClassName=LocalizationServiceTests\"\r\ndotnet test --filter \"ClassName=CommandLineArgumentConverterTests\"\r\n\r\n# 生成测试覆盖率报告\r\ndotnet test --collect:\"XPlat Code Coverage\"\r\n\r\n# 运行性能测试\r\ndotnet test --filter \"Category=Performance\"\r\n```\r\n\r\n### 测试特点\r\n\r\n- **全面覆盖**: 每个公共方法都有对应的测试用例\r\n- **边界测试**: 包含空值、边界值、异常情况的测试\r\n- **性能测试**: 对关键算法进行性能基准测试\r\n- **并发测试**: 验证线程安全的组件在多线程环境下的正确性\r\n- **兼容性测试**: 确保在不同.NET版本下的兼容性\r\n\r\n## 🏗️ 架构设计\r\n\r\n### 设计原则\r\n\r\n- **高性能**: 所有组件都经过性能优化，适用于高并发场景\r\n- **易用性**: 提供简洁的 API 设计，降低学习成本\r\n- **可扩展**: 模块化设计，支持自定义扩展\r\n- **类型安全**: 充分利用 .NET 的类型系统，减少运行时错误\r\n- **内存友好**: 使用 Span\u003cT\u003e 和 Memory\u003cT\u003e 等现代 .NET 特性，减少内存分配\r\n\r\n### 依赖关系\r\n\r\n```\r\nGameFrameX.Foundation.Extensions (核心扩展)\r\n├── GameFrameX.Foundation.Encryption (加密工具)\r\n├── GameFrameX.Foundation.Hash (哈希工具)\r\n├── GameFrameX.Foundation.Json (JSON工具)\r\n├── GameFrameX.Foundation.Logger (日志工具)\r\n├── GameFrameX.Foundation.Options (参数处理)\r\n├── GameFrameX.Foundation.Http.Extension (HTTP扩展)\r\n└── GameFrameX.Foundation.Http.Normalization (HTTP标准化)\r\n```\r\n\r\n## 🔧 开发指南\r\n\r\n### 环境要求\r\n\r\n- .NET 10.0 或更高版本\r\n- C# 12.0 或更高版本\r\n\r\n### 构建项目\r\n\r\n```bash\r\n# 克隆仓库\r\ngit clone https://github.com/GameFrameX/GameFrameX.Foundation.git\r\ncd GameFrameX.Foundation\r\n\r\n# 还原依赖\r\ndotnet restore\r\n\r\n# 构建项目\r\ndotnet build\r\n\r\n# 运行测试\r\ndotnet test\r\n```\r\n\r\n### 贡献指南\r\n\r\n1. Fork 本仓库\r\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\r\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\r\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\r\n5. 开启 Pull Request\r\n\r\n## 📊 性能基准\r\n\r\n### 扩展方法性能\r\n\r\n| 操作        | 传统方法  | 扩展方法  | 性能提升 |\r\n|-----------|-------|-------|------|\r\n| 字符串空值检查   | 100ns | 15ns  | 85%  |\r\n| 集合随机元素获取  | 200ns | 50ns  | 75%  |\r\n| Span 字节操作 | 500ns | 80ns  | 84%  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgameframex%2Fgameframex.foundation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgameframex%2Fgameframex.foundation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgameframex%2Fgameframex.foundation/lists"}