Merge branch "feature/http-streaming-parser" into main

Author: funnywwh

README.md

@@ -163,17 +163,22 @@ pub fn main() !void {
 - **说明**: 创建多个协程，展示时间片抢占调度效果
 
 ### 2. 网络服务器 (`nets/`)
-- **功能**: 基于 ZCO 的高性能 HTTP 服务器
+- **功能**: 基于 ZCO 的高性能 TCP 服务器基础模块
 - **运行**: `cd nets && zig build run`
-- **说明**: 支持高并发连接，展示 ZCO 在网络编程中的优势
+- **说明**: 提供 TCP 连接管理，展示 ZCO 在网络编程中的优势
 
-### 3. WebSocket 服务器 (`websocket/`)
+### 3. HTTP 框架 (`http/`)
+- **功能**: 完整的 HTTP 框架，支持路由、中间件、JWT、文件上传等
+- **运行**: `cd http && zig build run`
+- **说明**: 提供完整的 Web 开发功能，包含路由系统、中间件链、JWT认证、静态文件服务、模板引擎等
+
+### 4. WebSocket 服务器 (`websocket/`)
 - **功能**: 完整的 WebSocket 服务器实现
 - **运行**: `cd websocket && zig build run`
 - **测试**: `cd websocket/test && npm install && node client_test.js`
 - **说明**: 支持 RFC 6455 标准协议，包含完整的测试套件
 
-### 4. 性能对比测试 (`benchmarks/`)
+### 5. 性能对比测试 (`benchmarks/`)
 - **功能**: ZCO 与 Go 的性能对比测试套件
 - **运行**: `cd benchmarks && ./quick_test.sh`
 - **说明**: 提供完整的性能测试和对比分析
@@ -316,6 +321,7 @@ cd benchmarks
 - [x] 性能统计和监控
 - [x] 批量协程处理优化
 - [x] 网络服务器集成
+- [x] HTTP 框架模块（路由、中间件、JWT、文件上传、模板引擎）
 - [x] WebSocket 服务器模块（v0.4.2）
 - [x] 高并发压力测试验证
 - [x] 与 Go 的性能对比测试
@@ -325,6 +331,7 @@ cd benchmarks
 ### 待改进功能
 - [x] 优先级感知抢占（已实现环形缓冲区+优先级位图调度器）
 - [x] WebSocket 服务器支持（已实现）
+- [x] HTTP 框架支持（已实现）
 - [ ] 自适应时间片调整
 - [ ] 跨平台支持（Windows/macOS）
 - [ ] 更详细的性能监控

docs/FMT_FORMATTING_TROUBLESHOOTING.md

@@ -0,0 +1,228 @@
+# Zig fmt 格式化问题排查指南
+
+## 问题概述
+
+在 Zig 0.14.0 中，使用 `std.fmt` 进行字符串格式化时，如果参数是切片类型（slice），必须使用显式的格式说明符 `{s}` 或 `{any}`，而不能使用默认的 `{}`。这会导致编译错误：
+
+```
+error: cannot format slice without a specifier (i.e. {s} or {any})
+```
+
+## 问题定位过程
+
+### 初始错误
+
+项目在编译时遇到以下错误：
+```
+/home/winger/zig-linux-x86_64-0.14.0/lib/std/fmt.zig:653:21: error: cannot format slice without a specifier (i.e. {s} or {any})
+```
+
+### 排查策略
+
+采用**逐步屏蔽法**定位问题源：
+
+1. **屏蔽 main.zig 中的 fmt 调用** ✅
+2. **屏蔽 jwt.zig 中的 fmt 调用** ✅
+3. **屏蔽 response.zig 中的 fmt 调用** ✅
+4. **屏蔽 router/upload/static 中的 fmt 调用** ✅
+5. **定位并修复问题源** ✅
+
+### 问题根源
+
+最终定位到 `response.zig` 第 174 行：
+
+```zig
+// ❌ 错误写法
+try response_buf.writer().print("HTTP/1.1 {} {}\r\n", .{ self.status, status_text });
+
+// ✅ 正确写法
+try response_buf.writer().print("HTTP/1.1 {} {s}\r\n", .{ self.status, status_text });
+```
+
+**关键发现**：即使 `status_text` 是字符串字面量（字符串字面量在编译时是已知的），但在格式化时仍需要显式使用 `{s}` 格式说明符。
+
+## Zig 0.14.0 fmt 格式化规则
+
+### 格式说明符
+
+| 类型 | 格式说明符 | 示例 |
+|------|-----------|------|
+| 整数 | `{}` 或 `{d}` | `print("Count: {}", .{count})` |
+| 字符串/切片 | `{s}` 或 `{any}` | `print("Name: {s}", .{name})` |
+| 十六进制 | `{x}` | `print("Hex: {x}", .{value})` |
+| 指针 | `{*}` | `print("Ptr: {*}", .{ptr})` |
+| 任意类型 | `{any}` | `print("Value: {any}", .{value})` |
+
+### 常见错误场景
+
+#### 1. 字符串字面量格式化
+
+```zig
+// ❌ 错误：即使参数是字符串字面量，也需要 {s}
+const msg = "Hello";
+try writer.print("Message: {}\r\n", .{msg});
+
+// ✅ 正确
+const msg = "Hello";
+try writer.print("Message: {s}\r\n", .{msg});
+```
+
+#### 2. 动态字符串格式化
+
+```zig
+// ❌ 错误
+const name = try allocator.dupe(u8, "User");
+try writer.print("Name: {}", .{name});
+
+// ✅ 正确
+const name = try allocator.dupe(u8, "User");
+try writer.print("Name: {s}", .{name});
+```
+
+#### 3. 混合类型格式化
+
+```zig
+// ❌ 错误
+try writer.print("Status: {} {}\r\n", .{ status, message });
+
+// ✅ 正确
+try writer.print("Status: {} {s}\r\n", .{ status, message });
+```
+
+## 解决方案
+
+### 方案 1：使用正确的格式说明符（推荐）
+
+直接修复格式字符串，添加 `{s}` 说明符：
+
+```zig
+// 修复前
+try response_buf.writer().print("HTTP/1.1 {} {}\r\n", .{ self.status, status_text });
+
+// 修复后
+try response_buf.writer().print("HTTP/1.1 {} {s}\r\n", .{ self.status, status_text });
+```
+
+### 方案 2：使用 bufPrint（适用于小缓冲区）
+
+对于固定大小的缓冲区，可以使用 `bufPrint`：
+
+```zig
+var buf: [32]u8 = undefined;
+const len_str = try std.fmt.bufPrint(&buf, "{}", .{n});
+```
+
+### 方案 3：手动字符串拼接（临时方案）
+
+如果格式化功能暂时有问题，可以使用手动拼接：
+
+```zig
+// 临时方案：手动拼接
+var message = std.ArrayList(u8).init(allocator);
+defer message.deinit();
+try message.appendSlice("HTTP/1.1 ");
+try message.appendSlice(status_text);
+try message.appendSlice("\r\n");
+```
+
+## 最佳实践
+
+### 1. 格式化字符串时总是显式指定类型
+
+```zig
+// ✅ 推荐：显式类型
+try writer.print("Name: {s}, Age: {}, Score: {d}\r\n", .{ name, age, score });
+
+// ❌ 不推荐：依赖自动推断（可能导致错误）
+try writer.print("Name: {}, Age: {}, Score: {}\r\n", .{ name, age, score });
+```
+
+### 2. 使用 bufPrint 处理固定大小格式化
+
+```zig
+// 适用于：数字、小字符串
+var buf: [64]u8 = undefined;
+const formatted = try std.fmt.bufPrint(&buf, "Value: {}, Hex: {x}", .{ value, value });
+```
+
+### 3. 使用 allocPrint 处理动态大小格式化
+
+```zig
+// 适用于：长度未知的字符串
+const message = try std.fmt.allocPrint(allocator, "User {s} logged in", .{username});
+defer allocator.free(message);
+```
+
+### 4. 格式化时检查类型
+
+在开发过程中，如果遇到格式化错误，检查：
+- 参数是否是切片类型？
+- 如果是切片，是否使用了 `{s}` 或 `{any}`？
+- 格式字符串中的占位符数量是否与参数数量匹配？
+
+## 排查清单
+
+遇到 fmt 格式化错误时，按以下步骤排查：
+
+1. ✅ 检查格式字符串中的所有占位符
+2. ✅ 确认切片类型的参数使用了 `{s}` 或 `{any}`
+3. ✅ 验证占位符数量与参数数量匹配
+4. ✅ 检查是否有类型推断问题
+5. ✅ 尝试使用 `{any}` 进行调试（会显示完整类型信息）
+
+## 常见问题 FAQ
+
+### Q: 为什么字符串字面量也需要 `{s}`？
+
+A: 在 Zig 0.14.0 中，字符串字面量在格式化时被视为切片类型，必须显式指定格式说明符以提高类型安全性和代码可读性。
+
+### Q: `{s}` 和 `{any}` 有什么区别？
+
+A:
+- `{s}`：专门用于字符串/切片，进行字符串格式化
+- `{any}`：用于任意类型，会调用类型的 `format` 方法，显示调试信息
+
+### Q: 使用 `bufPrint` 和 `allocPrint` 的区别？
+
+A:
+- `bufPrint`：使用栈上的固定大小缓冲区，速度快，但大小受限
+- `allocPrint`：动态分配内存，大小灵活，但需要手动释放
+
+### Q: 如何避免此类错误？
+
+A:
+1. 在格式化字符串时总是显式指定类型
+2. 使用类型检查工具或 IDE 插件
+3. 建立代码审查规范，检查格式化调用
+
+## 修复记录
+
+### 修复的文件
+
+1. **http/src/response.zig**
+   - 修复位置：第 174 行
+   - 问题：`status_text` 未使用 `{s}` 格式说明符
+   - 修复：`"HTTP/1.1 {} {}\r\n"` → `"HTTP/1.1 {} {s}\r\n"`
+
+### 其他排查但未修复的位置（使用 bufPrint 处理）
+
+- `http/src/static.zig`: Content-Length 和 ETag 格式化
+- `http/src/main.zig`: Upload 消息格式化（用户已手动修复）
+
+## 参考资源
+
+- [Zig std.fmt 文档](https://ziglang.org/documentation/master/std/#std;fmt)
+- [Zig 0.14.0 Release Notes](https://ziglang.org/download/0.14.0/release-notes.html)
+- [Zig Learn - Formatting](https://ziglearn.org/chapter-1/#formatting)
+
+## 总结
+
+本次排查过程展示了 Zig 0.14.0 中 fmt 格式化的严格性。关键要点：
+
+1. **字符串/切片必须使用 `{s}` 或 `{any}`**
+2. **即使参数是字符串字面量也不例外**
+3. **采用逐步屏蔽法可以有效定位问题源**
+4. **显式类型说明符是推荐的编程实践**
+
+遵循这些规则可以避免类似的编译错误，提高代码质量和可维护性。
+