# Auto-route 模块

## 概述

Auto-route 模块是从 NetLeaf 主库分离出来的独立库，用于在404错误时自动查找相近的路由端点并在错误页面提示用户。

**版本**: 与主库共用版本号

**平台支持**:
- ✅ Windows
- ✅ Linux  
- ✅ macOS

## 功能特性

### 1. 智能路由匹配

使用Levenshtein距离算法计算路径相似度，支持多策略评分：

- **路径段匹配**: 逐个比较路径段的相似度
- **前缀共有**: 如果前缀相同给予额外加分
- **段数相同**: 如果路径段数相同给予额外加分

### 2. 路由建议

当用户访问不存在的路径时，自动查找最相似的现有路由并给出建议：

```
404 - Not Found
您访问的路径 "/api/user" 不存在。
您可能在找: /api/users
```

### 3. 灵活启用方式

支持多种启用/禁用方式：
- 整数: `1` (启用), `0` (禁用)
- 字符串: `"true"`, `"false"`, `"on"`, `"off"`, `"yes"`, `"no"` (大小写不敏感)

### 4. 通配符支持

支持路由模式匹配：
- `*` - 匹配任意字符（不包含 `/`）
- `**` - 匹配路径段

## API 参考

### 初始化与配置

| 函数 | 说明 |
|------|------|
| `nl_autoroute_init()` | 初始化模块 |
| `nl_autoroute_is_available()` | 检查模块是否可用 |
| `nl_autoroute_version()` | 获取模块版本 |

### 启用/禁用

| 函数 | 说明 |
|------|------|
| `nl_autoroute_enable(int)` | 启用/禁用模块（整数） |
| `nl_autoroute_enable_ex(const char*)` | 启用/禁用模块（字符串） |
| `nl_autoroute_is_enabled()` | 检查模块是否启用 |

### 路由匹配器

| 函数 | 说明 |
|------|------|
| `nl_route_matcher_create()` | 创建路由匹配器 |
| `nl_route_matcher_add_route()` | 添加单个路由 |
| `nl_route_matcher_add_routes()` | 批量添加路由 |
| `nl_route_matcher_destroy()` | 销毁匹配器 |

### 查找相似路由

| 函数 | 说明 |
|------|------|
| `nl_route_matcher_find_similar()` | 查找相似路由（返回最佳匹配） |
| `nl_route_matcher_get_suggestions()` | 获取多个建议 |

### 相似度计算

| 函数 | 说明 |
|------|------|
| `nl_route_similarity()` | 计算两个路径的相似度 |
| `nl_levenshtein_distance()` | 计算Levenshtein距离 |

### 辅助函数

| 函数 | 说明 |
|------|------|
| `nl_find_best_route()` | 从路由列表中查找最佳匹配 |
| `nl_route_matches()` | 检查路由模式是否匹配路径 |

### 全局匹配器

| 函数 | 说明 |
|------|------|
| `nl_autoroute_get_global_matcher()` | 获取全局路由匹配器 |
| `nl_autoroute_set_global_matcher()` | 设置全局路由匹配器 |
| `nl_autoroute_discover_routes()` | 自动发现路由 |

## 使用示例

```c
#include "netleaf_autoroute.h"

int main() {
    // 初始化模块
    nl_autoroute_init();
    
    // 启用模块
    nl_autoroute_enable_ex("true");
    
    // 获取全局路由匹配器
    nl_route_matcher_t* matcher = nl_autoroute_get_global_matcher();
    
    // 添加已知路由
    nl_route_matcher_add_route(matcher, "/api/users");
    nl_route_matcher_add_route(matcher, "/api/products");
    nl_route_matcher_add_route(matcher, "/dashboard");
    nl_route_matcher_add_route(matcher, "/login");
    
    // 查找相似路由
    char* suggestion = nl_route_matcher_find_similar(matcher, "/api/user", 0.4);
    // suggestion: "/api/users" (相似度0.75)
    
    // 获取多个建议
    nl_route_suggestion_t suggestions[5];
    int count = nl_route_matcher_get_suggestions(matcher, "/api/usre", suggestions, 5);
    
    free(suggestion);
    return 0;
}
```

## 相似度算法

### 算法说明

相似度评分由以下三部分组成：

1. **段平均相似度 (60%)**: 计算每个路径段的Levenshtein距离，取平均值
2. **段数相同奖励 (20%)**: 如果两个路径段数相同，给予额外加分
3. **前缀相同奖励 (20%)**: 如果路径前缀相同，给予额外加分

### 评分公式

```
score = avg_seg_sim * 0.6 + seg_count_bonus + prefix_bonus
```

### 示例

| 目标路径 | 候选路径 | 相似度 |
|---------|---------|--------|
| `/api/user` | `/api/users` | 0.75 |
| `/api/usre` | `/api/users` | 0.72 |
| `/api/products` | `/api/product` | 0.75 |
| `/dashboard` | `/dashbord` | 0.85 |
| `/login` | `/log` | 0.55 |

## 路由匹配模式

### 通配符说明

| 模式 | 说明 | 示例 |
|------|------|------|
| `*` | 匹配任意字符（不包含 `/`） | `/api/*` 匹配 `/api/users` |
| `**` | 匹配任意路径段 | `/**` 匹配所有路径 |

### 使用示例

```c
// 匹配所有API路径
nl_route_matches("/api/**", "/api/users/123");  // 返回 1

// 匹配任意子路径
nl_route_matches("/admin/*", "/admin/profile");  // 返回 1

// 精确匹配
nl_route_matches("/login", "/login");  // 返回 1
```

## 编译选项

```cmake
BUILD_AUTOROUTE=ON   # 默认启用
```

## 与ErrorPage模块联动

Auto-route模块可以与ErrorPage模块联动，在404错误页面中显示路由建议：

```c
// 在错误处理中
char* suggestion = nl_route_matcher_find_similar(matcher, requested_path, 0.4);

nl_errorpage_vars_t vars = {
    .status_code = 404,
    .error_message = "Not Found",
    .requested_path = requested_path,
    .suggestion = suggestion,  // 传递建议
    .server_version = "NetLeaf v2.4.0"
};

char* response = nl_errorpage_make_response(404, &vars);
free(suggestion);
```

## 注意事项

1. 该模块是独立库，可以单独编译和加载
2. 如果模块未加载，路由建议功能不可用，但不会影响主库运行
3. 建议在服务器启动时注册所有路由
4. 相似度阈值建议设置为0.4-0.6之间