# ErrorPage 模块
## 概述
ErrorPage 模块是从 NetLeaf 主库分离出来的独立库，用于支持自定义错误页面模板，强制预留变量区域，并可与 Auto-route 模块联动显示路由建议。
**版本**: 与主库共用版本号
**平台支持**:
- ✅ Windows
- ✅ Linux
- ✅ macOS
## 重要声明
⚠️ **该模块是独立的**
- 其他模块**不能**使用此模块的功能
- 如果该模块未编译/未加载，错误页面功能将**不可用**，但不会影响主库运行
- 必须预留变量区域，否则模板无效
## 功能特性
### 1. 模板系统
支持自定义HTML错误页面模板，提供灵活的错误页面定制能力。
### 2. 强制变量预留
自定义模板**必须**使用项目统一的变量格式 `{{变量名}}`，包含以下变量：
| 变量 | 说明 | 是否必需 |
|------|------|----------|
| `{{ERROR_CODE}}` | HTTP状态码（如404） | ✅ 必需 |
| `{{ERROR_MESSAGE}}` | 状态码描述（如"Not Found"） | ✅ 必需 |
| `{{REQUESTED_PATH}}` | 请求的路径 | ✅ 必需 |
| `{{SERVER_VERSION}}` | 服务器版本号 | ✅ 必需 |
| `{{TIMESTAMP}}` | 错误发生时间戳 | ✅ 必需 |
| `{{SUGGESTION}}` | 路由建议（可选） | 可选 |
**注意**: 此变量格式与项目中 `nl_web_add_html_with_vars()` 等函数使用的格式保持一致。
### 3. 灵活启用方式
支持多种启用/禁用方式：
- 整数: `1` (启用), `0` (禁用)
- 字符串: `"true"`, `"false"`, `"on"`, `"off"`, `"yes"`, `"no"` (大小写不敏感)
### 5. 与Auto-route联动
可以与 Auto-route 模块联动，在404错误页面中显示路由建议。
## API 参考
### 初始化与配置
| 函数 | 说明 |
|------|------|
| `nl_errorpage_init()` | 初始化模块 |
| `nl_errorpage_is_available()` | 检查模块是否可用 |
| `nl_errorpage_version()` | 获取模块版本 |
### 启用/禁用
| 函数 | 说明 |
|------|------|
| `nl_errorpage_enable(int)` | 启用/禁用模块（整数） |
| `nl_errorpage_enable_ex(const char*)` | 启用/禁用模块（字符串） |
| `nl_errorpage_is_enabled()` | 检查模块是否启用 |
### 模板加载与验证
| 函数 | 说明 |
|------|------|
| `nl_errorpage_load_template()` | 从文件加载模板 |
| `nl_errorpage_set_template()` | 设置模板内容 |
| `nl_errorpage_get_template()` | 获取指定状态码的模板 |
| `nl_errorpage_validate_template()` | 验证模板是否包含所有必需变量 |
### 错误页面渲染
| 函数 | 说明 |
|------|------|
| `nl_errorpage_render()` | 使用自定义模板渲染错误页面 |
| `nl_errorpage_render_default()` | 使用内置默认模板渲染 |
### HTTP响应生成
| 函数 | 说明 |
|------|------|
| `nl_errorpage_make_response()` | 生成完整的HTTP错误响应 |
| `nl_errorpage_make_response_custom()` | 使用自定义模板生成响应 |
| `nl_errorpage_quick_response()` | 快速生成简单错误响应 |
| `nl_errorpage_404_with_suggestion()` | 生成带路由建议的404响应 |
### 辅助函数
| 函数 | 说明 |
|------|------|
| `nl_errorpage_status_message()` | 获取状态码对应的默认消息 |
| `nl_errorpage_is_cacheable()` | 检查状态码是否可缓存 |
## 使用示例
### 基础使用
```c
#include "netleaf_errorpage.h"
int main() {
// 初始化模块
nl_errorpage_init();
// 启用模块
nl_errorpage_enable_ex("true");
// 生成简单错误响应
char* response = nl_errorpage_quick_response(404, "Not Found", "/badpath");
// 使用完毕后释放内存
free(response);
return 0;
}
```
### 使用自定义模板
```c
#include "netleaf_errorpage.h"
int main() {
nl_errorpage_init();
nl_errorpage_enable_ex("true");
// 设置自定义模板（必须包含所有必需变量，使用统一格式 {{VAR}}）
const char* template =
"\n"
"{{<var>ERROR_CODE</var>}} {{<var>ERROR_MESSAGE</var>}}\n"
"\n"
"{{ERROR_CODE}} - {{ERROR_MESSAGE}}
\n"
"您访问的路径: {{REQUESTED_PATH}} 不存在
\n"
"{{SUGGESTION}}
\n"
"\n"
"";
nl_errorpage_set_template(404, template);
// 生成错误响应
nl_errorpage_vars_t vars = {
.status_code = 404,
.error_message = "Not Found",
.requested_path = "/api/user",
.suggestion = "/api/users", // 来自Auto-route模块
.server_version = "NetLeaf v2.4.0"
};
char* response = nl_errorpage_make_response(404, &vars);
free(response);
return 0;
}
```
### 与Auto-route联动
```c
#include "netleaf_errorpage.h"
#include "netleaf_autoroute.h"
void handle_404(const char* requested_path) {
// 获取路由建议（来自Auto-route模块）
char* suggestion = NULL;
if (nl_autoroute_is_available() && nl_autoroute_is_enabled()) {
nl_route_matcher_t* matcher = nl_autoroute_get_global_matcher();
suggestion = nl_route_matcher_find_similar(matcher, requested_path, 0.4);
}
// 生成带建议的404响应
char* response = nl_errorpage_404_with_suggestion(requested_path, suggestion);
// 发送响应...
free(suggestion);
free(response);
}
```
## 内置默认模板
### 404模板
```html
{{<var>ERROR_CODE</var>}} {{<var>ERROR_MESSAGE</var>}}
{{ERROR_CODE}}
{{ERROR_MESSAGE}}
The requested path could not be found:
{{REQUESTED_PATH}}
{{
SUGGESTION}}
```
### 500模板
```html
{{<var>ERROR_CODE</var>}} {{<var>ERROR_MESSAGE</var>}}
{{ERROR_CODE}}
{{ERROR_MESSAGE}}
An internal server error occurred. Please try again later.
Path: {{REQUESTED_PATH}}
```
## 模板验证
模块提供模板验证功能，确保自定义模板包含所有必需变量：
```c
const char* template = "...";
if (nl_errorpage_validate_template(template)) {
printf("模板验证通过\n");
nl_errorpage_set_template(404, template);
} else {
printf("模板缺少必需变量\n");
}
```
## 支持的状态码
模块支持以下常见HTTP状态码的自定义模板：
| 状态码 | 说明 |
|--------|------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 408 | Request Timeout |
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
| 504 | Gateway Timeout |
## 编译选项
```cmake
BUILD_ERRORPAGE=ON # 默认启用
```
## 注意事项
1. **模块独立性**: ErrorPage模块是独立的，其他模块不能使用其功能
2. **变量强制性**: 自定义模板必须包含所有必需变量，否则验证失败
3. **联动限制**: 只能与Auto-route模块联动显示路由建议
4. **错误处理**: 如果模块未加载，错误页面功能不可用，但不会导致崩溃
5. **内存管理**: 生成的响应字符串需要调用者手动释放
## 与Auto-route的联动流程
```
用户请求不存在的路径
↓
服务器返回404
↓
Auto-route模块查找相似路由
↓
生成路由建议（如"/api/users"）
↓
ErrorPage模块渲染错误页面
↓
在错误页面中显示"您可能在找: /api/users"
```