## Trie 路由树（高性能路由）

### 简介
Trie 路由树是一种高性能的路由匹配结构，广泛应用于现代 Web 框架。相比传统的正则遍历路由，Trie 路由树在大规模路由和高并发场景下具有更高的查找效率。

### 特性
- 支持静态路由、命名参数（如 `/user/:id`）、通配符（如 `/static/*filepath`）
- 支持正则路由（如 `/user/(?P<id>[^/]+)`），正则路由单独分流
- 路由树根节点按 HTTP 方法（GET/POST/PUT/DELETE）分流，进一步提升查找效率
- 内置 LRU 路由缓存，热点路由命中极快
- 性能测试显示 Trie 路由树在大规模动态路由下性能优于传统正则遍历

### 用法
注册路由时，框架会自动将路由注册到 Trie 路由树和 HybridRouter：

```v
app.get('/api/users/:id', fn (req hono.Request) http.Response {
    return hono.Response.json('{"user_id": "${req.param["id"]}"}')
})
```

### 性能优势
- 静态路由、参数路由、通配符路由查找均为 O(n)（n为路径层级），极快
- 路由缓存命中时，查找仅需一次 map 查询，QPS 可达 20~30 万
- 支持上千条动态路由、百万级请求高并发场景

### 缓存说明
- Trie 路由树内置 LRU 缓存（默认容量1000），缓存 key 为 `method:path`，value 为 `RouteMatch`
- 命中缓存时性能极高，未命中时自动查找并写入缓存
- 可根据实际需求调整缓存容量

### 与 HybridRouter 对比
- HybridRouter 采用静态路由 map + 动态正则遍历，适合路由数量较少或兼容性需求高的场景
- TrieRouter 适合大规模路由、高并发、极致性能场景
- 两者可并存，便于灵活切换和对比测试

---

# 静态文件服务中间件

## 概述

为 V-Hono 框架添加了类似 Hono.js 的 `serveStatic` 中间件，提供高效、安全的静态文件服务功能。

## 实现文件

### 核心实现
- `hono/static.v` - 静态文件服务中间件的主要实现

### 示例文件
- `example.v` - 包含静态文件服务的完整示例

### 测试文件
- `public/index.html` - 默认索引文件
- `public/test.txt` - 测试文本文件
- `static/style.css` - 测试CSS文件
- `static/app.js` - 测试JavaScript文件
- `uploads/sample.json` - 测试JSON文件

## 核心功能

### 1. 静态文件服务中间件 (`serve_static`)

```v
pub fn serve_static(options StaticOptions) fn (mut Context, fn (mut Context) http.Response) http.Response
```

主要特性：
- 路径匹配和文件映射
- 安全检查（路径遍历攻击防护）
- 点文件访问控制
- 自动索引文件支持
- 智能错误处理

### 2. 配置选项 (`StaticOptions`)

```v
pub struct StaticOptions {
pub:
    root        string = './public'  // 静态文件根目录
    path        string = '/'         // URL路径前缀
    index       string = 'index.html' // 默认索引文件
    dotfiles    bool   = false       // 是否允许访问以.开头的文件
    etag        bool   = true        // 是否启用ETag
    last_modified bool = true        // 是否启用Last-Modified
    max_age     int    = 0           // 缓存时间（秒）
    headers     map[string]string    // 自定义响应头
}
```

### 3. 便捷函数

- `serve_static_default()` - 使用默认配置
- `serve_static_root(root string)` - 指定根目录
- `serve_static_path(path string, root string)` - 指定路径前缀和根目录

## 安全特性

### 路径遍历攻击防护

```v
fn is_safe_path(path string) bool {
    // 检查是否包含 .. 或绝对路径
    if path.contains('..') || path.starts_with('/') || path.starts_with('\\') {
        return false
    }
    
    // 检查是否包含危险字符
    dangerous_chars := ['<', '>', ':', '"', '|', '?', '*']
    for char in dangerous_chars {
        if path.contains(char) {
            return false
        }
    }
    
    return true
}
```

### 点文件访问控制

默认情况下阻止访问以 `.` 开头的文件，可通过 `dotfiles: true` 启用。

## 性能特性

### ETag 支持

```v
fn generate_etag(content string, mod_time i64) string {
    return '"${content.len}-${mod_time}"'
}
```

### 缓存控制

```v
if options.max_age > 0 {
    c.headers['Cache-Control'] = 'public, max-age=${options.max_age}'
} else {
    c.headers['Cache-Control'] = 'no-cache'
}
```

### Content-Type 检测

支持30+种文件类型的自动Content-Type检测：

```v
fn get_content_type(file_path string) string {
    ext := os.file_ext(file_path).to_lower()
    
    match ext {
        '.html', '.htm' { return 'text/html; charset=utf-8' }
        '.css' { return 'text/css; charset=utf-8' }
        '.js' { return 'application/javascript; charset=utf-8' }
        '.json' { return 'application/json; charset=utf-8' }
        // ... 更多类型
        else { return 'application/octet-stream' }
    }
}
```

## 使用示例

### 基本用法

```v
import hono

mut app := hono.Hono.new()

// 使用默认配置
app.use(hono.serve_static_default())

app.listen(':8080')
```

### 多目录配置

```v
// 默认静态文件
app.use(hono.serve_static_default())

// 资源文件
app.use(hono.serve_static_path('/assets', './static'))

// 上传文件
app.use(hono.serve_static_path('/uploads', './uploads'))
```

### 自定义配置

```v
options := hono.StaticOptions{
    root: './public'
    path: '/static'
    index: 'index.html'
    dotfiles: false
    etag: true
    last_modified: true
    max_age: 3600
    headers: {
        'X-Served-By': 'V-Hono'
    }
}

app.use(hono.serve_static(options))
```

## 与 Hono.js 的对比

| 特性 | V-Hono | Hono.js |
|------|--------|---------|
| 路径遍历防护 | ✅ | ✅ |
| 点文件控制 | ✅ | ✅ |
| ETag 支持 | ✅ | ✅ |
| Last-Modified | ✅ | ✅ |
| 缓存控制 | ✅ | ✅ |
| 自定义头部 | ✅ | ✅ |
| 自动索引文件 | ✅ | ✅ |
| Content-Type 检测 | ✅ | ✅ |
| 多目录支持 | ✅ | ✅ |

## 测试和验证

### 运行测试

```bash
# 完整示例
v run example.v
```

### 测试用例

1. **基本文件服务**
   - 访问 `public/test.txt` → `/test.txt`
   - 访问 `static/style.css` → `/assets/style.css`

2. **索引文件**
   - 访问目录 `/` → 提供 `public/index.html`

3. **安全测试**
   - 尝试路径遍历攻击 → 返回 403 Forbidden
   - 尝试访问点文件 → 返回 403 Forbidden

4. **缓存测试**
   - 检查 ETag 头
   - 检查 Last-Modified 头
   - 检查 Cache-Control 头

5. **Content-Type 测试**
   - 验证不同文件类型的正确 Content-Type

## 性能考虑

### 优化点

1. **文件读取**: 使用 V 语言的 `os.read_file()` 进行高效文件读取
2. **路径检查**: 快速的安全路径验证
3. **头部生成**: 高效的响应头构建
4. **缓存策略**: 可配置的缓存控制

### 内存使用

- 文件内容一次性读取到内存
- 适合中小型文件
- 大文件建议使用专门的CDN服务

## 未来改进

### 可能的增强

1. **流式文件服务**: 支持大文件的流式传输
2. **压缩支持**: 自动Gzip压缩
3. **范围请求**: 支持HTTP Range请求
4. **文件监控**: 文件变化时自动刷新缓存
5. **性能监控**: 添加性能指标收集

### 扩展性

当前实现具有良好的扩展性，可以轻松添加：
- 新的文件类型支持
- 自定义安全检查
- 更多的缓存策略
- 文件预处理功能

## 总结

成功为 V-Hono 框架添加了功能完整、安全可靠的静态文件服务中间件，提供了与 Hono.js 相当的体验，同时充分利用了 V 语言的特性。该实现具有良好的安全性、性能和易用性，可以满足大多数Web应用的静态文件服务需求。