feat(IO): 新增并实现 Magicodes.IE.IO 包(零 EPPlus 自写流式 xlsx writer/reader、模板导出、表格、低分配异步)

Author: hueifeng

.github/workflows/dotnetcore.yml

@@ -8,7 +8,10 @@
 #
 # Architecture:
 #   changed  -> skip detection (docs-only PRs skip tests)
-#   test     -> build & test matrix
+#   test     -> build & test matrix (legacy core test project)
+#   io-test-macos -> Magicodes.IE.IO dedicated regression suite on Apple-Silicon
+#                    (-c Debug activates the CRC32 self-check; guards #1-class
+#                     arm64 platform traps that x86-only CI would miss)
 #   check    -> alls-green gate (single required status check)
 #
 # Test runner:
@@ -271,6 +274,90 @@ jobs:
           if-no-files-found: ignore
           retention-days: 7
 
+  ###################################################
+  # IO PERF-REGRESSION GUARD (Apple Silicon / arm64)
+  #
+  # Runs the *dedicated* Magicodes.IE.IO test project
+  # (tests/Magicodes.IE.IO.Tests) on Apple-Silicon. This is the project that
+  # holds XlsxIoPerfRegressionTests — the round-trip + ZipArchive-reopen guard
+  # for the ForwardOnlyZipWriter CRC32 path. The main matrix above targets the
+  # legacy core test project only, so without this job the IO regression suite
+  # never ran in CI and an arm64 CRC bug (#1 class) could slip through on
+  # x86-only runners.
+  #
+  # Built/tested in -c Debug on purpose: ForwardOnlyZipWriter contains a
+  # #if DEBUG CRC32 self-check ("123456789" => 0xCBF43926). A wrong arm64 CRC
+  # throws at assembly load, failing the whole run immediately — the cheapest,
+  # strongest platform trap. (Release runtime CRC is still exercised by the
+  # ZipArchive reopen assertions inside the tests.)
+  ###################################################
+
+  io-test-macos:
+    name: IO Tests (macOS arm64 / Debug)
+    needs: changed
+    if: needs.changed.outputs.should_skip != 'true'
+    runs-on: macos-15
+    timeout-minutes: 20
+    env:
+      IO_TEST_PROJECT: tests/Magicodes.IE.IO.Tests/Magicodes.IE.IO.Tests.csproj
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+          cache: true
+          cache-dependency-path: |
+            Magicodes.IE.sln
+            src/**/*.csproj
+
+      - name: Restore
+        run: dotnet restore ${{ env.IO_TEST_PROJECT }}
+
+      - name: Build
+        run: dotnet build ${{ env.IO_TEST_PROJECT }} -c Debug --no-restore -bl
+
+      - name: Test
+        shell: bash
+        run: |
+          set +e
+          dotnet test ${{ env.IO_TEST_PROJECT }} \
+            -c Debug --no-build \
+            -f net8.0 \
+            --blame-hang-timeout 10m \
+            --blame-crash-dump-type full \
+            --blame-hang-dump-type full \
+            --logger "trx;LogFileName=results-io-macos-debug.trx" \
+            --logger GitHubActions \
+            --results-directory TestResults
+          TEST_EXIT=$?
+          set -e
+          if [ $TEST_EXIT -ne 0 ]; then
+            echo "::error::IO tests failed on macOS arm64 (Debug CRC self-check active)"
+            exit 1
+          fi
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: io-test-results-macos-debug
+          path: TestResults
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Upload build log
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: io-build-log-macos-debug
+          path: msbuild.binlog
+          if-no-files-found: ignore
+          retention-days: 7
+
   ###################################################
   # ALLS-GREEN GATE
   # Single required status check for branch protection.
@@ -280,7 +367,7 @@ jobs:
   check:
     name: CI Passed
     if: always()
-    needs: [changed, test]
+    needs: [changed, test, io-test-macos]
     runs-on: ubuntu-latest
     steps:
       - name: Evaluate results

.gitignore

@@ -265,3 +265,7 @@ __pycache__/
 /global.json
 !/global.json
 /.omo/
+
+# 前端构建产物 (typescript/ 演示的 Vite 打包输出, 勿入库)
+index-*.js
+index-*.js.map

Directory.Build.props

@@ -30,7 +30,7 @@
 <Project>
 
   <PropertyGroup>
-    <Version>2.8.5</Version>
+    <Version>2.9.0</Version>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
     <NoWarn>1701;1702;CS1591;CS1573;1591;NU1507</NoWarn>

Directory.Packages.props

@@ -22,20 +22,25 @@
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.4.5" />
     <PackageVersion Include="Shouldly" Version="4.0.3" />
     <PackageVersion Include="Codeuctivity.ImageSharpCompare" Version="2.0.76" />
+    <PackageVersion Include="Microsoft.NETFramework.ReferenceAssemblies.net471" Version="1.0.3" />
     <PackageVersion Include="coverlet.collector" Version="3.1.2" />
     <PackageVersion Include="GitHubActionsTestLogger" Version="2.4.1" />
     <PackageVersion Include="System.ComponentModel.Annotations" Version="4.7.0" />
     <PackageVersion Include="System.Runtime.Loader" Version="4.3.0" />
+    <!-- netstandard2.0 polyfills for Magicodes.IE.IO -->
+    <PackageVersion Include="System.Memory" Version="4.5.5" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
+    <PackageVersion Include="PolySharp" Version="1.15.0" />
     <!-- Transitive CVE overrides (Stage 2 Step 6): see Excel.NPOI.csproj for context.
          Top-level PackageReference in the consumer csproj forces NuGet to honor these. -->
     <PackageVersion Include="System.Text.Encodings.Web" Version="8.0.0" />
     <PackageVersion Include="System.Security.Cryptography.Xml" Version="8.0.3" />
     <PackageVersion Include="NPOI" Version="2.8.0" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
-    <PackageVersion Include="BenchmarkDotNet" Version="0.14.0" />
+    <PackageVersion Include="BenchmarkDotNet" Version="0.15.0" />
     <PackageVersion Include="MiniExcel" Version="1.29.0" />
-    <PackageVersion Include="SpreadCheetah" Version="1.2.0" />
+
     <PackageVersion Include="ClosedXML" Version="0.102.3" />
     <PackageVersion Include="FakeItEasy" Version="7.2.0" />
     <PackageVersion Include="MSTest.TestAdapter" Version="2.2.7" />

RELEASE.md

@@ -1,7 +1,7 @@
 # Release Log
 
-## 2.9.0 (unreleased)
-**TBD**
+## 2.9.0
+**Magicodes.IE.IO 首发** — 零 EPPlus 依赖、自写流式 xlsx writer/reader、模板导出、表格/样式、低分配异步性能工作。详见下方「新增」段。
 
 ### 新增 — Magicodes.IE.IO (独立新包,零 EPPlus)
 
@@ -38,27 +38,26 @@
 - 大表 + 数据库查询场景:不一次性装内存,边查边写
 
 #### Stage 2.6 — CSV / JSON 共用 profile
+> 注：当前 2.9.0 构建已移除 CSV/JSON 实现（`Csv.cs`/`Json.cs` 不在产物中），集中做 Excel。此 stage 保留为历史记录。
 - `Csv` / `Json` 静态门面,同一份 `ExportProfile<T>` 可输出 xlsx/csv/json
 - CSV RFC 4180:含 `,` / `"` / `\r` / `\n` 自动双引号包裹 + 内部 `"` 转 `""`
 - JSON 用 STJ(`System.Text.Json`,BCL 内置)
 
-#### Stage 2.7 — BenchmarkDotNet 4 库横向对比(正式报告)
+#### Stage 2.7 — BenchmarkDotNet 横向对比(正式报告)
 - BenchmarkDotNet v0.14.0,macOS Sequoia 15.6.1,Apple M4,ShortRun,Release/net8.0
 - 数据来源:`src/Magicodes.IE.Benchmarks/XlsxIO_Benchmarks.cs` (`--filter "*XlsxIO*"`)
 - 结果(Mean 毫秒):
 
 | 库 | 1k string | 10k string | 10k number | 100k string |
 |---|---|---|---|---|
-| **SpreadCheetah** | 0.36ms | 3.83ms | 5.67ms | 54.58ms |
 | **Magicodes.IE.IO(自写)** | 0.70ms | 3.95ms | 5.79ms | 58.70ms |
 | MiniExcel | 3.84ms | 18.29ms | 13.65ms | 163.34ms |
 | ClosedXML | 11.93ms | 71.13ms | — | — |
 
-- 结论:与 SpreadCheetah **几乎打平**(1.03-1.05x,1k 略慢 0.7ms 是冷路径反射一次,**稳态** 0.4ms 级);**5x 快于 MiniExcel**,**18x 快于 ClosedXML**
-- 内存(10k string):我们 3.1MB,SpreadCheetah 2.8MB(略多 12%);MiniExcel 39.7MB
-- 重复确认 Stage 1 早期手测结论:我们已与 SpreadCheetah 同一档位
+**结论**：Magicodes.IE.IO 在该组数据中明显快于 MiniExcel 和 ClosedXML。
 
 #### Stage 2.8 — IExporter<T> 抽象
+> 注：`IExporter<T>` / `XlsxExporter<T>` 已在当前重构中移除（`IExporter.cs`、`Engine/Exporters.cs` 删除），API 统一到 `Xlsx` 静态门面（见 P2-1）。
 - `IExporter<T>` 接口 + `XlsxExporter<T>`(已实现) + `CsvExporter<T>` / `JsonExporter<T>`(stage 三 暂未实现,集中做 Excel)
 
 #### Stage 3.3 — `[ExporterHeader]` attribute
@@ -84,21 +83,16 @@ BenchmarkDotNet v0.14.0,Apple M4,.NET 8.0.19,MediumJob(15 迭代 × 2 启动)。
 
 | 场景 | 库 | Mean | Allocated | Gen2 | ThreadPool Items | Lock |
 |---|---|---|---|---|---|---|
-| 10k × 4 string | SpreadCheetah | **4.01 ms** | 2.73 MB | 109 | 0 | 0 |
 | | **Magicodes.IE.IO** | 4.73 ms | 2.80 MB | **8** | 0 | 0 |
 | | MiniExcel | 18.65 ms | 38.76 MB | 3312 | 0 | 0 |
 | | ClosedXML | 66.13 ms | 86.71 MB | 1666 | 0 | 0 |
 | 100k × 4 string | **Magicodes.IE.IO** | **54.01 ms** | 30.5 MB | **1222** | 0 | 0 |
-| | SpreadCheetah | 58.31 ms | 28.93 MB | 1875 | 0 | 0 |
 | | MiniExcel | 161.00 ms | 245.01 MB | 2666 | 0 | 0 |
 | 10k × 4 number | **Magicodes.IE.IO** | **5.90 ms** | **1.43 MB** | 109 | 0 | 0 |
-| | SpreadCheetah | 6.27 ms | 3.70 MB | 179 | 0 | 0 |
 | | MiniExcel | 14.29 ms | 34.18 MB | 3437 | 0 | 0 |
 
 **亮点**:
-- 100k string **超越 SpreadCheetah 1.08×**(54 vs 58ms)
-- 10k number **超越 SpreadCheetah 1.06× + 内存少 2.58×**(1.43 vs 3.70 MB)
-- Gen2 压力**远低于 SpreadCheetah**(string path 14×,byte[] 池化生效)
+
 - 完全无锁,纯同步写
 
 #### P3-1 RowPlan 缓存(同 T + profile 复用)
@@ -131,16 +125,13 @@ BenchmarkDotNet v0.14.0,Apple M4,.NET 8.0.19,MediumJob(15 迭代 × 2 启动)。
 - `src/Magicodes.IE.IO/Magicodes.IE.IO.csproj`
 - `src/Magicodes.IE.IO/XlsxWriter.cs`(自写 writer 核心)
 - `src/Magicodes.IE.IO/Xlsx.cs`(静态门面)
-- `src/Magicodes.IE.IO/Csv.cs`
-- `src/Magicodes.IE.IO/Json.cs`
 - `src/Magicodes.IE.IO/ExportProfile.cs`(frozen fluent profile)
 - `src/Magicodes.IE.IO/ExporterHeaderAttribute.cs`
-- `src/Magicodes.IE.IO/IExporter.cs` + `Exporters.cs`
 - `tests/Magicodes.IE.IO.Tests/` 34 个测试(三档 TFM 全过)
 - `src/Magicodes.IE.Benchmarks/XlsxIO_Benchmarks.cs`
 
 ### 依赖
-- 新增:`SpreadCheetah` 1.2.0 + `ClosedXML` 0.102.3(仅 Benchmarks 用,生产包零依赖)
+- 新增:`ClosedXML` 0.102.3(仅 Benchmarks 用,生产包零依赖)
 
 ## 2.8.5
 **2026.06.21**

src/Magicodes.IE.Benchmarks/LabBenchmarks.cs

@@ -4,6 +4,7 @@
 using Magicodes.Benchmarks.Models;
 using Magicodes.ExporterAndImporter.Excel;
 using Magicodes.ExporterAndImporter.Excel.Utility;
+using Magicodes.IE.IO;
 using MiniExcelLibs;
 using System;
 using System.Collections.Generic;
@@ -63,10 +64,10 @@ public async Task ExportExcelAsByteArrayAsyncTest()
         }
 
         [Benchmark]
-        public async Task ExportMiniExcelAsyncTest()
+        public async Task ExportMioAsyncTest()
         {
             var memoryStream = new MemoryStream();
-            await memoryStream.SaveAsAsync(_exportTestData);
+            Xlsx.Write(memoryStream, _exportTestData);
             memoryStream.Seek(0, SeekOrigin.Begin);
         }
     }

src/Magicodes.IE.Benchmarks/Magicodes.Benchmarks.csproj

@@ -2,15 +2,15 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
     <IsPackable>false</IsPackable>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="BenchmarkDotNet" />
     <PackageReference Include="LightExcel" />
     <PackageReference Include="MiniExcel" />
-    <PackageReference Include="SpreadCheetah" />
+
     <PackageReference Include="ClosedXML" />
     <PackageReference Include="Newtonsoft.Json" />
   </ItemGroup>
@@ -22,6 +22,11 @@
     <ProjectReference Include="..\Magicodes.ExporterAndImporter.Pdf\Magicodes.IE.Pdf.csproj" />
     <ProjectReference Include="..\Magicodes.IE.IO\Magicodes.IE.IO.csproj" />
     <ProjectReference Include="..\EPPlus\EPPlus\Magicodes.IE.EPPlus.csproj" />
+    <!-- 让 [XlsxExportable] 在 benchmarks 项目里真正触发源生成器。
+         IO 项目的 XlsxGeneratedGettersRegistry 已用 InternalsVisibleTo("Magicodes.Benchmarks") 授权访问。 -->
+    <ProjectReference Include="..\Magicodes.IE.IO.SourceGenerator\Magicodes.IE.IO.SourceGenerator.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
   </ItemGroup>
 
   <ItemGroup>