003 《Kore Web 框架权威指南》
备注：Gemini 2.0 Flash Thinking 创作的书籍，用来辅助学习。
书籍大纲 📚
▮▮▮▮ chapter 1： Kore Web 框架简介 🚀
▮▮▮▮▮▮▮ 1.1 什么是 Kore？ 🤔
▮▮▮▮▮▮▮ 1.2 Kore 的特点和优势 ✨
▮▮▮▮▮▮▮ 1.3 Kore 的应用场景 🌐
▮▮▮▮▮▮▮ 1.4 环境搭建与快速开始 🛠️
▮▮▮▮ chapter 2： Kore 框架核心概念 🧠
▮▮▮▮▮▮▮ 2.1 请求处理流程 ➡️
▮▮▮▮▮▮▮ 2.2 路由 (Routing) 🧭
▮▮▮▮▮▮▮ 2.3 中间件 (Middleware) 🔗
▮▮▮▮▮▮▮ 2.4 配置管理 ⚙️
▮▮▮▮ chapter 3： Kore API 详解 - HTTP 处理 🌐
▮▮▮▮▮▮▮ 3.1 请求 (Request) 对象 📤
▮▮▮▮▮▮▮ 3.2 响应 (Response) 对象 📥
▮▮▮▮▮▮▮ 3.3 会话 (Session) 管理 🔒
▮▮▮▮▮▮▮ 3.4 Cookie 处理 🍪
▮▮▮▮ chapter 4： Kore API 详解 - 数据处理与存储 💾
▮▮▮▮▮▮▮ 4.1 数据库集成 (Database Integration) 🗄️
▮▮▮▮▮▮▮ 4.2 数据模型 (Data Models) 📊
▮▮▮▮▮▮▮ 4.3 缓存 (Caching) ⚡️
▮▮▮▮▮▮▮ 4.4 文件上传与处理 📂
▮▮▮▮ chapter 5： Kore API 详解 - 异步与并发 🚦
▮▮▮▮▮▮▮ 5.1 异步编程 (Asynchronous Programming) ⏳
▮▮▮▮▮▮▮ 5.2 并发处理 (Concurrency) 👯
▮▮▮▮▮▮▮ 5.3 WebSocket 支持 💬
▮▮▮▮▮▮▮ 5.4 事件驱动编程 (Event-Driven Programming) 🕹️
▮▮▮▮ chapter 6： Kore 应用开发实践 💻
▮▮▮▮▮▮▮ 6.1 项目结构与组织 🏗️
▮▮▮▮▮▮▮ 6.2 模板引擎 (Template Engine) 📄
▮▮▮▮▮▮▮ 6.3 表单处理与验证 (Form Handling and Validation) ✅
▮▮▮▮▮▮▮ 6.4 身份验证与授权 (Authentication and Authorization) 🔑
▮▮▮▮ chapter 7： Kore 安全性 🛡️
▮▮▮▮▮▮▮ 7.1 常见 Web 安全漏洞 ⚠️
▮▮▮▮▮▮▮ 7.2 Kore 的安全特性 💯
▮▮▮▮▮▮▮ 7.3 安全开发最佳实践 🧑💻
▮▮▮▮ chapter 8： Kore 测试与部署 ✅🚀
▮▮▮▮▮▮▮ 8.1 单元测试 (Unit Testing) 🧪
▮▮▮▮▮▮▮ 8.2 集成测试 (Integration Testing) 🔗
▮▮▮▮▮▮▮ 8.3 性能测试 (Performance Testing) 📊
▮▮▮▮▮▮▮ 8.4 部署到生产环境 (Deployment to Production) ☁️
▮▮▮▮ chapter 9： Kore 高级主题 🌟
▮▮▮▮▮▮▮ 9.1 自定义中间件 (Custom Middleware) 🛠️
▮▮▮▮▮▮▮ 9.2 Kore 扩展开发 (Extending Kore) 🧩
▮▮▮▮▮▮▮ 9.3 性能优化 (Performance Optimization) 🚀
▮▮▮▮▮▮▮ 9.4 与其他技术的集成 (Integration with other technologies) 🤝
▮▮▮▮ chapter 10： 案例研究 (Case Studies) 💡
▮▮▮▮▮▮▮ 10.1 构建 RESTful API 🌐
▮▮▮▮▮▮▮ 10.2 构建实时应用 💬
▮▮▮▮▮▮▮ 10.3 构建 CMS 系统 📰
▮▮▮▮ 附录 A： Kore API 参考 📚
▮▮▮▮ 附录 B： 常见问题解答 (FAQ) ❓
1. chapter 1： Kore Web 框架简介 🚀
1.1 什么是 Kore？ 🤔
Kore 是一个专为构建可扩展的 Web 应用而设计的 Web 框架（Web Framework）。它以 C 语言 开发，并以其高性能、安全性和灵活性而著称。与许多基于 解释型语言（Interpreted Language）的框架不同，Kore 利用 C 语言 的底层优势，提供了卓越的性能，这使得它成为构建需要处理高并发和低延迟应用的理想选择。
Kore 的设计哲学强调简洁和高效。它避免了不必要的抽象和复杂性，力求提供一个轻量级但功能强大的平台，让开发者能够专注于业务逻辑的实现，而不是框架本身的复杂性。这并不意味着 Kore 缺乏功能；相反，它提供了一系列核心功能，如 路由（Routing）、中间件（Middleware）、WebSocket 支持等，同时保持了代码库的精简和性能的优越。
1.2 Kore 的特点和优势 ✨
Kore Web 框架之所以在众多 Web 开发框架中脱颖而出，得益于其独特的技术特点和优势：
① 卓越的性能：
▮▮▮▮ⓐ C 语言的优势：Kore 使用 C 语言 编写，这是一种编译型语言，直接编译成机器码执行，避免了解释型语言的运行时开销。这使得 Kore 在处理请求时拥有更高的效率和更低的资源消耗。
▮▮▮▮ⓑ 事件驱动架构（Event-Driven Architecture）：Kore 采用了 事件驱动 的非阻塞 I/O 模型，能够高效地处理大量并发连接，而无需为每个连接创建独立的线程或进程，从而显著提升了系统的吞吐量和响应速度。
② 安全性：
▮▮▮▮ⓐ 代码库精简：Kore 的代码库相对较小，这降低了代码审查的难度，并减少了潜在的安全漏洞。
▮▮▮▮ⓑ 内存安全（Memory Safety）：C 语言 虽然需要开发者手动管理内存，但 Kore 的开发团队在框架设计和实现上非常注重内存安全，努力避免常见的内存错误，如缓冲区溢出等。此外，Kore 也鼓励开发者遵循安全的编程实践。
③ 灵活性和可扩展性：
▮▮▮▮ⓐ 模块化设计（Modular Design）：Kore 采用模块化设计，核心功能与扩展功能分离，开发者可以根据项目需求选择性地使用所需模块，也可以方便地扩展框架的功能。
▮▮▮▮ⓑ 底层控制：由于 Kore 基于 C 语言，开发者可以更接近底层操作系统，进行更精细的性能调优和资源控制，这对于需要极致性能的应用至关重要。
④ 易用性：
▮▮▮▮ⓐ 简洁的 API（Application Programming Interface）：Kore 提供了清晰且文档完善的 API，使得开发者能够快速上手并高效地开发 Web 应用。
▮▮▮▮ⓑ 快速开发：尽管 Kore 使用 C 语言，但其设计目标之一是提高开发效率。通过提供常用的 Web 开发组件和工具，Kore 使得开发者能够更快地构建功能丰富的 Web 应用。
1.3 Kore 的应用场景 🌐
Kore Web 框架凭借其高性能、安全性和灵活性，在多种应用场景中都表现出色：
① 高性能 API 服务：对于需要处理高并发请求和快速响应的 API 服务，Kore 是一个理想的选择。例如，构建金融交易平台、实时数据接口或高流量电商平台的后端服务。
② 实时应用：Kore 对 WebSocket 的原生支持，使其非常适合构建实时性要求高的应用，如在线聊天应用、实时监控系统、多人在线游戏服务端等。
③ 嵌入式系统和物联网 (IoT)：Kore 的轻量级和低资源消耗特性，使其可以运行在资源受限的 嵌入式系统（Embedded System）和 物联网（Internet of Things, IoT）设备上，为这些设备提供 Web 服务能力。
④ 安全敏感型应用：对于安全性要求极高的应用，如金融系统、安全监控系统等，Kore 的安全特性和 C 语言 的底层控制能力，能够提供更可靠的安全保障。
⑤ 微服务架构（Microservices Architecture）：在 微服务架构 中，各个服务通常需要快速响应和高效运行。Kore 可以作为构建高性能微服务的框架，提升整个系统的性能和稳定性。
1.4 环境搭建与快速开始 🛠️
要开始使用 Kore Web 框架进行开发，首先需要搭建开发环境。以下是在常见操作系统上搭建 Kore 环境的简要步骤：
1.4.1 前提条件
① 操作系统：支持 Linux, macOS, FreeBSD, OpenBSD 等 类 Unix 系统（Unix-like System）。
② C 编译器（C Compiler）：例如 gcc 或 clang。
③ make：构建工具。
④ pkg-config (可选，但推荐)：用于管理库的编译和链接选项。
⑤ openssl 库和头文件：用于 HTTPS 支持。
⑥ pcre 库和头文件：用于 正则表达式（Regular Expression）处理。
⑦ zlib 库和头文件：用于 gzip 压缩。
1.4.2 下载 Kore
可以通过 git 命令克隆 Kore 的 GitHub 仓库（GitHub Repository）：
1
git clone https://github.com/kore-projects/kore.git
2
cd kore
1.4.3 编译和安装 Kore
在 Kore 源代码目录下，执行以下命令进行编译和安装：
1
make
2
sudo make install
这个过程会将 Kore 的可执行文件和库文件安装到系统目录中，通常是 /usr/local/bin 和 /usr/local/lib。
1.4.4 创建一个简单的 Kore 应用
创建一个名为 hello.c 的文件，并输入以下代码：
1
#include <kore.h>
2
3
int hello(struct http_request *);
4
5
int
6
hello(struct http_request *req)
7
{
8
http_response_header(req, "Content-Type", "text/plain");
9
http_response(req, 200, "Hello, Kore!", 12);
10
return (KORE_RESULT_OK);
11
}
12
13
int
14
kore_main(int argc, char *argv[])
15
{
16
kore_http_handler_add("/hello", hello);
17
return (KORE_RESULT_OK);
18
}
这段代码定义了一个简单的 HTTP 处理函数 hello()，当访问 /hello 路径时，会返回 "Hello, Kore!"。kore_main() 函数用于添加路由规则，将 /hello 路径映射到 hello() 函数。
1.4.5 编译和运行应用
使用以下命令编译 hello.c：
1
kore-cc hello.c -o hello
然后运行编译生成的可执行文件 hello：
1
./hello
默认情况下，Kore 会监听 http://localhost:8888。在浏览器中访问 http://localhost:8888/hello，如果看到 "Hello, Kore!"，则表示环境搭建成功，你的第一个 Kore 应用已经运行起来了！ 🎉
通过以上步骤，你已经成功搭建了 Kore Web 框架的开发环境，并创建并运行了一个简单的 "Hello, Kore!" 应用。接下来，我们将深入学习 Kore 框架的更多核心概念和 API，以便构建更复杂的 Web 应用。
2. chapter 2： Kore 框架核心概念 🧠
2.1 请求处理流程 ➡️
理解 Kore Web 框架的 请求处理流程（Request Processing Flow）是深入学习和高效开发的基础。当一个客户端（例如浏览器）发起一个 HTTP 请求（HTTP Request）到 Kore 服务器时，请求会经历一系列处理步骤，最终生成 HTTP 响应（HTTP Response）返回给客户端。以下是 Kore 请求处理流程的概览：
① 接收请求（Receiving Request）：
当 Kore 服务器接收到一个来自客户端的网络连接请求时，它首先建立连接并接收客户端发送的 HTTP 请求报文（HTTP Request Message）。这个过程由 Kore 的底层网络模块负责处理，使用了高效的 I/O 多路复用（I/O Multiplexing）技术，例如 epoll (Linux), kqueue (BSD)。
② 解析请求（Parsing Request）：
接收到完整的 HTTP 请求报文 后，Kore 会对请求报文进行解析，提取出请求方法（Method，例如 GET, POST）、请求路径（Path）、HTTP 头部（HTTP Headers）、请求体（Body）等信息。这个解析过程非常高效，旨在快速提取关键信息，以便后续的路由和处理。
③ 路由匹配（Route Matching）：
请求解析完成后，Kore 会根据请求的路径，在预先定义的 路由表（Routing Table）中查找匹配的 路由规则（Routing Rule）。路由 的作用是将不同的请求路径映射到不同的处理函数（Handler）。Kore 的路由匹配非常快速，支持 静态路由（Static Routing）和 动态路由（Dynamic Routing），以及 正则表达式（Regular Expression）匹配。
④ 中间件执行（Middleware Execution）：
在找到匹配的路由规则后，请求会经过一系列 中间件（Middleware）的处理。中间件 是在请求处理过程中插入的组件，用于执行通用的、与业务逻辑无关的任务，例如日志记录（Logging）、身份验证（Authentication）、请求头修改等。中间件 按照预定义的顺序依次执行，每个 中间件 都可以选择是否继续传递请求到下一个 中间件 或直接终止请求并返回响应。
⑤ 处理器执行（Handler Execution）：
当请求经过所有 中间件 的处理后，最终会到达与路由匹配的处理函数（Handler）。处理器 是负责处理具体业务逻辑的函数，例如从数据库查询数据、处理用户输入、生成动态内容等。处理器 接收请求对象作为参数，并负责生成 HTTP 响应。
⑥ 生成响应（Generating Response）：
处理器 执行完成后，会生成 HTTP 响应 对象。响应 对象包含了 HTTP 状态码（HTTP Status Code，例如 200 OK, 404 Not Found）、HTTP 头部 以及 响应体（Response Body，例如 HTML 内容、JSON 数据）。
⑦ 发送响应（Sending Response）：
Kore 服务器将 HTTP 响应 对象序列化为 HTTP 响应报文，并通过网络连接发送回客户端。发送完成后，连接可以保持打开状态（例如对于 Keep-Alive 连接）以便处理后续请求，或者关闭连接。
⑧ 日志记录和清理（Logging and Cleanup）：
在请求处理的最后阶段，Kore 可能会进行日志记录，记录请求处理的详细信息，例如请求时间、客户端 IP 地址、请求路径、响应状态码等。同时，还会进行资源清理，释放请求处理过程中使用的内存和文件句柄等资源。
下图展示了 Kore 的请求处理流程：
1
graph LR
2
A[接收请求] --> B(解析请求)
3
B --> C{路由匹配}
4
C -- 匹配 --> D[中间件 1]
5
D --> E[中间件 2]
6
E --> F{...}
7
F --> G[中间件 N]
8
G --> H{处理器执行}
9
H --> I[生成响应]
10
I --> J[发送响应]
11
J --> K[日志记录和清理]
12
C -- 不匹配 --> L[404 响应]
13
L --> J
2.2 路由 (Routing) 🧭
路由（Routing）是 Web 框架的核心组件之一，它负责将接收到的 HTTP 请求 映射到相应的处理函数。Kore 提供了强大且灵活的路由机制，允许开发者定义各种路由规则，以满足不同应用的需求。
2.2.1 静态路由
静态路由（Static Routing）是最简单的路由形式，它将固定的 URL 路径映射到特定的处理函数。例如，将 / 路径映射到首页处理函数，将 /about 路径映射到关于页面处理函数。
在 Kore 中，可以使用 kore_http_handler_add() 函数添加静态路由。例如，以下代码将 /hello 路径映射到 hello_handler() 函数：
1
#include <kore.h>
2
3
int hello_handler(struct http_request *);
4
5
int
6
hello_handler(struct http_request *req)
7
{
8
http_response_header(req, "Content-Type", "text/plain");
9
http_response(req, 200, "Hello from static route!", 24);
10
return (KORE_RESULT_OK);
11
}
12
13
int
14
kore_main(int argc, char *argv[])
15
{
16
kore_http_handler_add("/hello", hello_handler);
17
return (KORE_RESULT_OK);
18
}
2.2.2 动态路由
动态路由（Dynamic Routing）允许在 URL 路径中使用 占位符（Placeholder），以匹配一类路径，并将占位符的值传递给处理函数。这使得我们可以处理例如 /user/{id} 这样的路径，其中 {id} 可以是不同的用户 ID。
Kore 使用特殊的语法来定义动态路由，例如使用尖括号 <> 包裹占位符。以下示例展示了如何定义一个动态路由，匹配 /user/{id} 路径，并将 id 参数传递给处理函数：
1
#include <kore.h>
2
#include <kore/http.h>
3
4
int user_handler(struct http_request *);
5
6
int
7
user_handler(struct http_request *req)
8
{
9
const char *user_id = http_request_path_parameter(req, "id");
10
if (user_id == NULL) {
11
http_response(req, 400, "Missing user ID", 15);
12
return (KORE_RESULT_ERROR);
13
}
14
15
http_response_header(req, "Content-Type", "text/plain");
16
http_response(req, 200, "User ID: ", 9);
17
http_response_stream(req, user_id, strlen(user_id));
18
return (KORE_RESULT_OK);
19
}
20
21
int
22
kore_main(int argc, char *argv[])
23
{
24
kore_http_handler_add("/user/<id>", user_handler);
25
return (KORE_RESULT_OK);
26
}
在 user_handler() 函数中，我们使用 http_request_path_parameter() 函数来获取名为 "id" 的路径参数的值。
2.2.3 正则表达式路由
正则表达式路由（Regular Expression Routing）提供了最强大的路由匹配能力，允许使用 正则表达式 来定义路由规则。这可以处理更复杂的路径匹配需求。
在 Kore 中，可以使用 kore_http_handler_add_regex() 函数添加正则表达式路由。例如，以下代码使用正则表达式匹配以 /api/v[0-9]+ 开头的路径：
1
#include <kore.h>
2
#include <kore/http.h>
3
4
int api_handler(struct http_request *);
5
6
int
7
api_handler(struct http_request *req)
8
{
9
http_response_header(req, "Content-Type", "text/plain");
10
http_response(req, 200, "API endpoint hit!", 17);
11
return (KORE_RESULT_OK);
12
}
13
14
int
15
kore_main(int argc, char *argv[])
16
{
17
kore_http_handler_add_regex("^/api/v[0-9]+", api_handler);
18
return (KORE_RESULT_OK);
19
}
这个路由规则会匹配 /api/v1, /api/v2, /api/v10 等路径。
2.2.4 路由优先级
当定义了多个路由规则时，Kore 需要确定哪个路由规则应该被优先匹配。Kore 的路由优先级规则如下：
① 静态路由优先于动态路由和正则表达式路由。如果一个请求路径同时匹配静态路由和动态路由（或正则表达式路由），静态路由会被优先匹配。
② 动态路由优先于正则表达式路由。如果一个请求路径同时匹配动态路由和正则表达式路由，动态路由会被优先匹配。
③ 按照路由添加的顺序。如果多个路由规则都匹配同一个请求路径，那么先添加的路由规则会被优先匹配。
理解路由优先级对于设计复杂的路由规则至关重要，可以避免路由冲突和意外的匹配结果。
2.3 中间件 (Middleware) 🔗
中间件（Middleware）是在请求处理流程中插入的组件，它位于路由匹配之后、处理器执行之前。中间件 可以拦截和处理 HTTP 请求 和 响应，执行通用的、横切关注点的任务，例如：
① 日志记录（Logging）：记录请求的详细信息，例如请求时间、客户端 IP 地址、请求路径等。
② 身份验证（Authentication）：验证用户的身份，例如检查用户是否已登录。
③ 授权（Authorization）：检查用户是否有权限访问请求的资源。
④ 请求头修改（Request Header Modification）：修改请求头，例如添加或删除请求头。
⑤ 响应头修改（Response Header Modification）：修改响应头，例如设置 Content-Type 或 Cache-Control。
⑥ 错误处理（Error Handling）：捕获和处理请求处理过程中发生的错误。
⑦ 压缩（Compression）：对响应内容进行压缩，例如使用 gzip 压缩。
中间件 采用 洋葱模型（Onion Model），请求会依次通过 中间件 链，每个 中间件 都可以对请求进行处理，并决定是否将请求传递给下一个 中间件 或直接返回响应。当响应返回时，也会按照相反的顺序再次经过 中间件 链。
2.3.1 全局中间件
全局中间件（Global Middleware）会应用于所有的 HTTP 请求。可以使用 kore_http_middleware_register() 函数注册全局中间件。例如，以下代码注册了一个简单的全局日志记录中间件：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <time.h>
4
5
int logger_middleware(struct http_request *, void *);
6
7
int
8
logger_middleware(struct http_request *req, void *arg)
9
{
10
time_t timer;
11
char buffer[26];
12
struct tm* tm_info;
13
14
time(&timer);
15
tm_info = localtime(&timer);
16
17
strftime(buffer, 26, "%Y-%m-%d %H:%M:%S", tm_info);
18
19
kore_log(LOG_INFO, "[%s] %s %s", buffer, req->method_str, req->path);
20
return (KORE_RESULT_OK); // 继续处理请求
21
}
22
23
int
24
kore_main(int argc, char *argv[])
25
{
26
kore_http_middleware_register(logger_middleware, NULL);
27
kore_http_handler_add("/", hello_handler); // 假设 hello_handler 已定义
28
return (KORE_RESULT_OK);
29
}
logger_middleware() 函数会在每个请求到达时被调用，记录请求的时间、方法和路径。return (KORE_RESULT_OK); 表示继续将请求传递给下一个 中间件 或处理器。
2.3.2 路由中间件
路由中间件（Route Middleware）只应用于特定的路由规则。可以在添加路由规则时指定要应用的 中间件。例如，以下代码为 /admin 路径添加了一个身份验证中间件 auth_middleware()：
1
#include <kore.h>
2
#include <kore/http.h>
3
4
int auth_middleware(struct http_request *, void *);
5
int admin_handler(struct http_request *);
6
7
int
8
auth_middleware(struct http_request *req, void *arg)
9
{
10
// 假设的身份验证逻辑
11
if (!is_authenticated(req)) { // is_authenticated() 是一个假设的函数
12
http_response(req, 401, "Unauthorized", 12);
13
return (KORE_RESULT_ERROR); // 终止请求
14
}
15
return (KORE_RESULT_OK); // 继续处理请求
16
}
17
18
int
19
admin_handler(struct http_request *req, void *arg)
20
{
21
http_response_header(req, "Content-Type", "text/plain");
22
http_response(req, 200, "Admin area", 10);
23
return (KORE_RESULT_OK);
24
}
25
26
27
int
28
kore_main(int argc, char *argv[])
29
{
30
kore_http_handler_add_middleware("/admin", auth_middleware, admin_handler);
31
return (KORE_RESULT_OK);
32
}
只有当请求路径匹配 /admin 时，auth_middleware() 才会执行。如果 auth_middleware() 返回 KORE_RESULT_ERROR，请求处理会立即终止，并返回 401 Unauthorized 响应。
2.3.3 中间件顺序
中间件 的执行顺序非常重要。全局 中间件 会在所有路由 中间件 之前执行，而路由 中间件 则按照其注册的顺序执行。在同一个路由上注册的多个 中间件 也按照注册顺序执行。
合理的 中间件 顺序可以有效地组织请求处理逻辑，例如，通常会将日志记录 中间件 放在最前面，以便记录所有请求；将身份验证和授权 中间件 放在业务逻辑 中间件 之前，以确保安全性。
2.4 配置管理 ⚙️
配置管理（Configuration Management）是任何应用程序的重要组成部分。Kore 提供了灵活的配置管理机制，允许开发者通过配置文件或命令行参数来配置应用程序的行为。
Kore 的配置文件通常是 kore.conf，默认情况下，Kore 会在启动时加载当前目录下的 kore.conf 文件。可以使用 -f 命令行参数指定配置文件的路径。
2.4.1 配置文件语法
kore.conf 文件使用简单的 键值对（Key-Value Pair）语法，每行一个配置项，格式为 key = value。
① 注释：以 # 开头的行是注释。
② 字符串值：字符串值可以使用双引号 " 或单引号 ' 包裹，也可以不包裹，但如果值包含空格或特殊字符，则必须包裹。
③ 布尔值：布尔值可以使用 yes, no, true, false, on, off, 1, 0 表示。
④ 整数值：整数值可以直接书写。
⑤ 列表值：列表值可以使用逗号 , 分隔，并用方括号 [] 包裹。
例如，一个简单的 kore.conf 文件可能如下所示：
1
# Kore configuration file
2
3
server "http" {
4
listen = "0.0.0.0:8888"
5
processes = 4
6
}
7
8
accesslog "/var/log/kore/access.log"
9
10
tls {
11
certificate = "/etc/kore/tls/server.crt"
12
key = "/etc/kore/tls/server.key"
13
}
14
15
database "mydb" {
16
driver = "pgsql"
17
host = "localhost"
18
port = 5432
19
user = "koreuser"
20
password = "password123"
21
database = "koredb"
22
}
23
24
allowed_hosts = ["example.com", "www.example.com"]
2.4.2 常用的配置项
以下是一些常用的 Kore 配置项：
① server "http" { ... }：配置 HTTP 服务器。
▮▮▮▮ⓐ listen：监听地址和端口，例如 "0.0.0.0:8888", "[::]:80", "127.0.0.1:9000".
▮▮▮▮ⓑ processes：工作进程数，用于处理并发请求。通常设置为 CPU 核心数。
▮▮▮▮ⓒ backlog：监听队列长度，用于处理高并发连接。
▮▮▮▮ⓓ max_request_body：最大请求体大小限制。
② accesslog "path"：配置 访问日志 文件路径。
③ errorlog "path"：配置 错误日志 文件路径。
④ tls { ... }：配置 TLS/HTTPS。
▮▮▮▮ⓐ certificate： TLS 证书 文件路径。
▮▮▮▮ⓑ key： TLS 私钥 文件路径。
▮▮▮▮ⓒ protocols：允许的 TLS 协议 版本，例如 "tlsv1.2 tlsv1.3".
⑤ database "name" { ... }：配置 数据库连接。
▮▮▮▮ⓐ driver：数据库驱动，例如 "pgsql", "mysql", "sqlite3".
▮▮▮▮ⓑ host：数据库服务器主机名或 IP 地址。
▮▮▮▮ⓒ port：数据库服务器端口号。
▮▮▮▮ⓓ user：数据库用户名。
▮▮▮▮ⓔ password：数据库密码。
▮▮▮▮ⓕ database：数据库名称。
⑥ allowed_hosts = [...]：配置允许的主机名列表，用于防止 主机头攻击（Host Header Attack）。
2.4.3 在代码中访问配置
可以使用 Kore 提供的 API 在代码中访问配置项的值。例如，使用 kore_config_lookup_string() 函数获取字符串配置值，使用 kore_config_lookup_integer() 函数获取整数配置值，等等。
1
#include <kore.h>
2
3
int
4
kore_main(int argc, char *argv[])
5
{
6
const char *listen_address;
7
int processes;
8
9
listen_address = kore_config_lookup_string("server.http.listen");
10
if (listen_address != NULL) {
11
kore_log(LOG_INFO, "Listen address: %s", listen_address);
12
}
13
14
processes = kore_config_lookup_integer("server.http.processes", 0); // 默认值 0
15
kore_log(LOG_INFO, "Processes: %d", processes);
16
17
return (KORE_RESULT_OK);
18
}
通过灵活的配置管理，Kore 允许开发者根据不同的环境和需求调整应用程序的行为，提高了应用程序的可配置性和可部署性。
Chapter 2 详细介绍了 Kore Web 框架的核心概念，包括请求处理流程、路由、中间件和配置管理。理解这些概念是深入学习 Kore 和构建高效、可靠 Web 应用的关键。在接下来的章节中，我们将深入探讨 Kore 的 API 细节，并进行实际的应用开发。
3. chapter 3： Kore API 详解 - HTTP 处理 🌐
3.1 请求 (Request) 对象 📤
在 Kore Web 框架中，当服务器接收到一个 HTTP 请求 时，会将其封装成一个 struct http_request 对象，并传递给 处理器（Handler）和 中间件（Middleware）函数。这个对象包含了关于请求的所有信息，例如请求方法、路径、头部、查询参数、请求体等。通过操作 struct http_request 对象，开发者可以获取请求的详细信息，并进行相应的处理。
struct http_request 对象的主要成员和相关 API 可以分为以下几个方面：
① 请求方法 (Method)：
⚝ req->method：表示 HTTP 请求方法 的枚举值，例如 HTTP_METHOD_GET, HTTP_METHOD_POST, HTTP_METHOD_PUT, HTTP_METHOD_DELETE 等。
⚝ req->method_str：表示 HTTP 请求方法 的字符串形式，例如 "GET", "POST", "PUT", "DELETE" 等。
例如，判断请求方法是否为 GET：
1
if (req->method == HTTP_METHOD_GET) {
2
// 处理 GET 请求
3
}
获取请求方法的字符串形式：
1
kore_log(LOG_INFO, "Request method: %s", req->method_str);
② 请求路径 (Path)：
⚝ req->path：表示请求的路径部分，例如 /index.html, /api/users。
获取请求路径：
1
const char *path = req->path;
2
kore_log(LOG_INFO, "Request path: %s", path);
③ 查询参数 (Query Parameters)：
⚝ http_request_query_string(req)：获取完整的 查询字符串（Query String），例如 "param1=value1¶m2=value2"。
⚝ http_request_query_parameter(req, name)：根据参数名 name 获取 查询参数 的值。
获取完整的查询字符串：
1
const char *query_string = http_request_query_string(req);
2
if (query_string != NULL) {
3
kore_log(LOG_INFO, "Query string: %s", query_string);
4
}
获取指定查询参数的值：
1
const char *param1_value = http_request_query_parameter(req, "param1");
2
if (param1_value != NULL) {
3
kore_log(LOG_INFO, "Parameter param1: %s", param1_value);
4
}
④ 路径参数 (Path Parameters)：
⚝ http_request_path_parameter(req, name)：用于获取 动态路由 中定义的 路径参数 的值，参数名 name 需要与路由定义中的占位符名称一致。
例如，对于路由 /user/<id>，获取路径参数 id 的值：
1
const char *user_id = http_request_path_parameter(req, "id");
2
if (user_id != NULL) {
3
kore_log(LOG_INFO, "User ID: %s", user_id);
4
}
⑤ 头部 (Headers)：
⚝ http_request_header(req, name)：根据头部名称 name 获取 请求头 的值。
⚝ http_request_header_count(req)：获取 请求头 的数量。
⚝ http_request_header_name(req, index)：根据索引 index 获取 请求头 的名称。
⚝ http_request_header_value(req, index)：根据索引 index 获取 请求头 的值。
获取指定请求头的值：
1
const char *user_agent = http_request_header(req, "User-Agent");
2
if (user_agent != NULL) {
3
kore_log(LOG_INFO, "User-Agent: %s", user_agent);
4
}
遍历所有请求头：
1
int header_count = http_request_header_count(req);
2
for (int i = 0; i < header_count; i++) {
3
const char *header_name = http_request_header_name(req, i);
4
const char *header_value = http_request_header_value(req, i);
5
kore_log(LOG_INFO, "Header %s: %s", header_name, header_value);
6
}
⑥ 请求体 (Body)：
⚝ req->http_body：指向 请求体 数据的指针。
⚝ req->http_body_len：表示 请求体 数据的长度。
⚝ http_request_body_raw(req, &len)：获取原始的 请求体 数据指针和长度。
⚝ http_request_body_string(req)：将 请求体 数据作为字符串返回 (需要请求体是文本类型)。
⚝ http_request_body_json(req)：将 请求体 数据解析为 JSON 对象 (需要请求体是 JSON 格式)。
⚝ http_request_body_form(req)：将 请求体 数据解析为 表单 数据 (需要请求体是 application/x-www-form-urlencoded 或 multipart/form-data 格式)。
获取原始请求体数据：
1
void *body_data;
2
size_t body_len;
3
body_data = http_request_body_raw(req, &body_len);
4
if (body_data != NULL) {
5
kore_log(LOG_INFO, "Request body length: %zu", body_len);
6
// 处理 body_data 中的数据
7
}
将请求体解析为 JSON 对象：
1
struct json_value *json_body = http_request_body_json(req);
2
if (json_body != NULL) {
3
// 处理 JSON 对象
4
json_value_free(json_body); // 记得释放 JSON 对象
5
} else if (req->http_body != NULL) {
6
kore_log(LOG_WARNING, "Failed to parse request body as JSON");
7
}
⑦ 客户端信息 (Client Information)：
⚝ req->client_ip：客户端 IP 地址的字符串表示。
⚝ req->client_port：客户端端口号。
获取客户端 IP 地址和端口：
1
kore_log(LOG_INFO, "Client IP: %s", req->client_ip);
2
kore_log(LOG_INFO, "Client Port: %d", req->client_port);
⑧ 其他信息：
⚝ req->proto：HTTP 协议 版本，例如 "HTTP/1.1", "HTTP/2".
⚝ req->start：请求开始处理的时间戳。
⚝ req->state：请求的当前状态。
3.2 响应 (Response) 对象 📥
struct http_request 对象不仅用于获取请求信息，也用于构建和发送 HTTP 响应。Kore 提供了丰富的 API 来设置响应状态码、头部、响应体等。
用于构建 HTTP 响应 的主要 API 包括：
① 设置状态码 (Status Code)：
⚝ http_response_status(req, status_code)：设置 HTTP 响应状态码，例如 200 (OK), 404 (Not Found), 500 (Internal Server Error) 等。
设置状态码为 200 OK：
1
http_response_status(req, 200);
② 设置头部 (Headers)：
⚝ http_response_header(req, name, value)：设置 响应头，可以多次调用以设置多个头部。
设置 Content-Type 头部：
1
http_response_header(req, "Content-Type", "text/plain");
设置多个头部：
1
http_response_header(req, "Content-Type", "application/json");
2
http_response_header(req, "Cache-Control", "no-cache");
③ 设置响应体 (Body)：
⚝ http_response(req, status_code, body, length)：设置 响应状态码 和 响应体，一次性发送完整的响应体数据。
⚝ http_response_stream(req, body_part, length)：流式发送 响应体 数据，可以多次调用以发送分块数据。
⚝ http_response_open(req, status_code, content_type)：开始流式响应，设置 状态码 和 Content-Type 头部，之后可以使用 http_response_stream() 发送数据。
⚝ http_response_close(req)：结束流式响应。
⚝ http_response_sendfile(req, path)：发送文件作为 响应体。
⚝ http_response_json(req, status_code, json_value)：发送 JSON 数据作为 响应体，并自动设置 Content-Type: application/json 头部。
发送文本响应：
1
http_response(req, 200, "Hello, World!", 13);
流式发送响应：
1
http_response_open(req, 200, "text/plain");
2
http_response_stream(req, "Part 1", 6);
3
http_response_stream(req, "Part 2", 6);
4
http_response_close(req);
发送 JSON 响应：
1
struct json_value *root = json_object();
2
json_object_push(root, "message", json_string("Hello, JSON!"));
3
http_response_json(req, 200, root);
4
json_value_free(root); // 记得释放 JSON 对象
发送文件响应：
1
http_response_sendfile(req, "/path/to/file.txt");
④ 重定向 (Redirect)：
⚝ http_response_redirect(req, status_code, url)：发送 重定向响应，状态码通常为 301 (Moved Permanently) 或 302 (Found)。
发送 302 重定向：
1
http_response_redirect(req, 302, "/new-location");
⑤ 错误响应 (Error Responses)：
⚝ http_response_error(req, status_code)：发送通用的错误响应，状态码如 400, 404, 500 等。Kore 会根据状态码自动生成默认的错误页面。
发送 404 Not Found 错误响应：
1
http_response_error(req, 404);
3.3 会话 (Session) 管理 🔒
会话（Session）管理是 Web 应用中常用的技术，用于在多次请求之间维护用户状态。Kore 提供了内置的 会话管理 功能，支持基于 Cookie 的会话跟踪。
Kore 会话管理 的主要 API 包括：
① 创建或获取会话：
⚝ http_session_create(req)：为当前请求创建一个新的 会话。如果客户端没有发送有效的 会话 Cookie，或者会话不存在，则会创建一个新的会话。
⚝ http_session_get(req)：获取当前请求的 会话 对象。如果客户端发送了有效的 会话 Cookie，并且会话存在，则返回会话对象；否则返回 NULL。
创建或获取会话：
1
struct http_session *session = http_session_create(req);
2
if (session == NULL) {
3
kore_log(LOG_ERR, "Failed to create session");
4
http_response_error(req, 500);
5
return (KORE_RESULT_ERROR);
6
}
获取会话：
1
struct http_session *session = http_session_get(req);
2
if (session != NULL) {
3
// 会话存在，可以访问会话数据
4
} else {
5
// 会话不存在
6
}
② 会话数据操作：
⚝ http_session_set_string(session, key, value)：设置 会话数据，键 key 和值 value 都是字符串。
⚝ http_session_get_string(session, key)：获取 会话数据 中键 key 对应的值，返回字符串。
⚝ http_session_remove_key(session, key)：从 会话数据 中移除键 key。
设置会话数据：
1
http_session_set_string(session, "user_id", "123");
2
http_session_set_string(session, "username", "example_user");
获取会话数据：
1
const char *user_id = http_session_get_string(session, "user_id");
2
if (user_id != NULL) {
3
kore_log(LOG_INFO, "Session user_id: %s", user_id);
4
}
移除会话数据：
1
http_session_remove_key(session, "username");
③ 会话销毁：
⚝ http_session_destroy(req, session)：销毁 会话，并清除客户端的 会话 Cookie。
销毁会话：
1
struct http_session *session = http_session_get(req);
2
if (session != NULL) {
3
http_session_destroy(req, session);
4
}
④ 会话配置：
Kore 的 会话管理 行为可以通过配置文件 kore.conf 进行配置，例如：
1
session {
2
cookie_name = "KoreSessionId"
3
cookie_httponly = yes
4
cookie_secure = yes
5
timeout = 3600 # 会话超时时间，单位秒
6
}
⚝ cookie_name：会话 Cookie 的名称，默认为 "Kore-Session".
⚝ cookie_httponly：是否设置 HttpOnly 标志，防止客户端 JavaScript 访问 Cookie，默认为 yes。
⚝ cookie_secure：是否设置 Secure 标志，只在 HTTPS 连接中发送 Cookie，默认为 yes。
⚝ timeout：会话超时时间，单位秒，默认为 3600 (1 小时)。
3.4 Cookie 处理 🍪
Cookie 是 Web 开发中常用的客户端存储技术，用于在客户端浏览器中存储少量数据，并在后续请求中发送回服务器。Kore 提供了 API 来设置和获取 Cookie。
Kore Cookie 处理 的主要 API 包括：
① 设置 Cookie：
⚝ http_response_cookie_set(req, name, value, options)：设置 Cookie。options 参数是一个 struct http_cookie_options 结构体，用于配置 Cookie 的属性。
struct http_cookie_options 结构体的成员包括：
1
* `path`：Cookie 的有效路径，默认为 `"/"` (整个域名)。
2
* `domain`：Cookie 的有效域名，默认为当前域名。
3
* `max_age`：Cookie 的最大生存时间，单位秒。如果设置为 0 或负数，则 **Cookie** 会在浏览器关闭时删除 (会话 **Cookie**)。
4
* `httponly`：是否设置 **HttpOnly** 标志，默认为 `kore_config->cookie_httponly` (配置文件中的 `cookie_httponly` 配置项)。
5
* `secure`：是否设置 **Secure** 标志，默认为 `kore_config->cookie_secure` (配置文件中的 `cookie_secure` 配置项)。
6
* `samesite`：设置 **SameSite** 属性，防止 **跨站请求伪造**（Cross-Site Request Forgery, CSRF）攻击，可选值包括 `HTTP_COOKIE_SAMESITE_NONE`, `HTTP_COOKIE_SAMESITE_LAX`, `HTTP_COOKIE_SAMESITE_STRICT`.
设置一个简单的 Cookie：
1
http_response_cookie_set(req, "my_cookie", "cookie_value", NULL);
设置带选项的 Cookie：
1
struct http_cookie_options options;
2
memset(&options, 0, sizeof(options));
3
options.max_age = 86400; // 24 小时
4
options.httponly = 1;
5
options.secure = 1;
6
options.samesite = HTTP_COOKIE_SAMESITE_LAX;
7
8
http_response_cookie_set(req, "my_cookie", "cookie_value", &options);
② 获取 Cookie：
⚝ http_request_cookie(req, name)：根据 Cookie 名称 name 获取 Cookie 的值。
获取 Cookie 的值：
1
const char *cookie_value = http_request_cookie(req, "my_cookie");
2
if (cookie_value != NULL) {
3
kore_log(LOG_INFO, "Cookie my_cookie: %s", cookie_value);
4
}
③ 删除 Cookie：
通过设置 max_age 为 0 或负数，可以删除客户端已存在的 Cookie。
删除 Cookie：
1
struct http_cookie_options options;
2
memset(&options, 0, sizeof(options));
3
options.max_age = -1; // 设置为负数，立即删除 Cookie
4
5
http_response_cookie_set(req, "my_cookie", "", &options); // value 可以为空字符串
Chapter 3 详细介绍了 Kore Web 框架中处理 HTTP 请求 和 响应 的 API，包括请求对象的访问、响应对象的构建、会话管理和 Cookie 处理。掌握这些 API 是进行 Web 应用开发的基础。在接下来的章节中，我们将继续深入学习 Kore 的其他功能和 API。
4. chapter 4： Kore API 详解 - 数据处理与存储 💾
4.1 数据库集成 (Database Integration) 🗄️
Kore Web 框架虽然自身不包含完整的 对象关系映射（Object-Relational Mapping, ORM）系统，但提供了与多种 关系型数据库（Relational Database）集成的能力。通过 Kore 提供的 数据库 API，开发者可以在 Kore 应用中方便地进行数据库操作，例如查询、插入、更新、删除数据等。
Kore 主要通过以下方式实现数据库集成：
① 数据库驱动（Database Driver）：
Kore 支持多种常见的 关系型数据库，并为每种数据库提供了相应的 驱动（Driver）。目前官方支持的数据库驱动包括：
* PostgreSQL：使用 libpq 库。
* MySQL / MariaDB：使用 libmysqlclient 库。
* SQLite3：使用 libsqlite3 库。
在 kore.conf 配置文件中，可以通过 database 块配置数据库连接信息，并指定使用的驱动。例如，配置 PostgreSQL 数据库连接：
1
database "mydb" {
2
driver = "pgsql"
3
host = "localhost"
4
port = 5432
5
user = "koreuser"
6
password = "password123"
7
database = "koredb"
8
max_connections = 10 # 可选，最大连接数
9
}
② 数据库连接管理（Database Connection Management）：
Kore 负责管理数据库连接的创建、复用和释放。在配置数据库连接后，Kore 会在需要时自动建立连接，并在请求处理完成后释放连接。开发者无需手动管理连接的生命周期，这简化了数据库操作的复杂性。
可以使用 kore_database_get() 函数获取已配置的数据库连接。函数原型如下：
1
struct kore_database *kore_database_get(const char *name);
name 参数是在 kore.conf 中配置的 database 块的名称。函数返回指向 struct kore_database 对象的指针，如果找不到指定名称的数据库配置，则返回 NULL。
③ 数据库操作 API：
Kore 提供了统一的 API 来执行数据库操作，例如执行 SQL 查询、获取查询结果、处理事务等。这些 API 屏蔽了不同数据库驱动的差异，使得开发者可以使用相同的代码来操作不同的数据库。
常用的数据库操作 API 包括：
1
* **执行 SQL 查询**：
2
* `kore_database_query(db, query, ...)`：执行 **SQL** 查询，并返回查询结果。
3
* `kore_database_query_va(db, query, ap)`：与 `kore_database_query()` 类似，但使用 `va_list` 传递参数。
4
* `kore_database_query_async(db, query, callback, arg, ...)`：异步执行 **SQL** 查询，并在查询完成后调用回调函数 `callback`。
5
* `kore_database_query_async_va(db, query, callback, arg, ap)`：异步执行 **SQL** 查询，并使用 `va_list` 传递参数。
6
7
* **处理查询结果**：
8
* `kore_database_result(result)`：获取查询结果对象。
9
* `kore_database_result_next_row(result)`：移动到结果集的下一行。
10
* `kore_database_result_get_string(result, column_index)`：获取当前行指定列的字符串值。
11
* `kore_database_result_get_integer(result, column_index)`：获取当前行指定列的整数值。
12
* `kore_database_result_get_double(result, column_index)`：获取当前行指定列的浮点数值。
13
* `kore_database_result_get_blob(result, column_index, &len)`：获取当前行指定列的 **BLOB** (Binary Large Object) 值和长度。
14
* `kore_database_result_free(result)`：释放查询结果对象。
15
16
* **事务处理**：
17
* `kore_database_begin(db)`：开始一个数据库事务。
18
* `kore_database_commit(db)`：提交当前事务。
19
* `kore_database_rollback(db)`：回滚当前事务。
4.1.1 数据库操作示例
以下示例展示了如何使用 Kore 数据库 API 进行基本的数据库操作，假设已经配置了一个名为 "mydb" 的 PostgreSQL 数据库连接。
① 查询数据：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <kore/pgsql.h> // 如果使用 PostgreSQL
4
5
int users_handler(struct http_request *);
6
7
int
8
users_handler(struct http_request *req)
9
{
10
struct kore_database *db;
11
struct kore_pgsql *pgsql; // 如果使用 PostgreSQL
12
struct kore_db_result *result = NULL;
13
int ret = KORE_RESULT_OK;
14
15
db = kore_database_get("mydb"); // 获取数据库连接
16
if (db == NULL) {
17
kore_log(LOG_ERR, "Failed to get database connection");
18
http_response_error(req, 500);
19
return (KORE_RESULT_ERROR);
20
}
21
22
pgsql = (struct kore_pgsql *)db->driver_data; // 获取 PostgreSQL 驱动数据，如果需要
23
24
result = kore_database_query(db, "SELECT id, username FROM users"); // 执行 SQL 查询
25
if (result == NULL) {
26
kore_log(LOG_ERR, "Database query failed: %s", kore_database_error(db));
27
http_response_error(req, 500);
28
ret = KORE_RESULT_ERROR;
29
goto cleanup;
30
}
31
32
http_response_header(req, "Content-Type", "application/json");
33
http_response_open(req, 200, "application/json");
34
http_response_stream(req, "[", 1); // JSON 数组开始
35
36
int first_row = 1;
37
while (kore_database_result_next_row(result)) { // 遍历结果集
38
if (!first_row) {
39
http_response_stream(req, ",", 1); // JSON 数组元素分隔符
40
} else {
41
first_row = 0;
42
}
43
44
char id_str[32];
45
int id = kore_database_result_get_integer(result, 0); // 获取 id 列的值
46
snprintf(id_str, sizeof(id_str), "%d", id);
47
const char *username = kore_database_result_get_string(result, 1); // 获取 username 列的值
48
49
char json_row[256]; // 假设每行 JSON 数据不会超过 256 字节
50
snprintf(json_row, sizeof(json_row), "{\"id\":%s,\"username\":\"%s\"}", id_str, username);
51
http_response_stream(req, json_row, strlen(json_row));
52
}
53
54
http_response_stream(req, "]", 1); // JSON 数组结束
55
http_response_close(req);
56
57
58
cleanup:
59
if (result != NULL) {
60
kore_database_result_free(result); // 释放结果集
61
}
62
return (ret);
63
}
64
65
int
66
kore_main(int argc, char *argv[])
67
{
68
kore_http_handler_add("/users", users_handler);
69
return (KORE_RESULT_OK);
70
}
② 插入数据：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <kore/pgsql.h> // 如果使用 PostgreSQL
4
5
int create_user_handler(struct http_request *);
6
7
int
8
create_user_handler(struct http_request *req)
9
{
10
struct kore_database *db;
11
struct kore_pgsql *pgsql; // 如果使用 PostgreSQL
12
int ret = KORE_RESULT_OK;
13
14
db = kore_database_get("mydb"); // 获取数据库连接
15
if (db == NULL) {
16
kore_log(LOG_ERR, "Failed to get database connection");
17
http_response_error(req, 500);
18
return (KORE_RESULT_ERROR);
19
}
20
21
pgsql = (struct kore_pgsql *)db->driver_data; // 获取 PostgreSQL 驱动数据，如果需要
22
23
const char *username = http_request_body_string(req); // 假设请求体是用户名字符串
24
if (username == NULL) {
25
http_response_error(req, 400); // Bad Request
26
return KORE_RESULT_ERROR;
27
}
28
29
if (kore_database_query(db, "INSERT INTO users (username) VALUES ($1)", username) == NULL) { // 使用参数化查询
30
kore_log(LOG_ERR, "Database insert failed: %s", kore_database_error(db));
31
http_response_error(req, 500);
32
ret = KORE_RESULT_ERROR;
33
goto cleanup;
34
}
35
36
http_response(req, 201, "User created", 12); // 201 Created
37
38
cleanup:
39
return (ret);
40
}
41
42
int
43
kore_main(int argc, char *argv[])
44
{
45
kore_http_handler_add("/users", create_user_handler);
46
return (KORE_RESULT_OK);
47
}
注意：在实际开发中，应该使用 参数化查询（Parameterized Query）或 预编译语句（Prepared Statement）来防止 SQL 注入（SQL Injection）攻击。Kore 的 kore_database_query() 函数支持参数化查询，可以使用 $1, $2, ... 占位符，并在后续参数中提供对应的值。
4.2 数据模型 (Data Models) 📊
Kore Web 框架本身并没有内置 ORM 系统或特定的 数据模型（Data Model）定义方式。开发者需要根据项目需求，自行设计和实现 数据模型。在 Kore 应用中，数据模型 通常是指在代码中表示应用程序数据的结构和类。
以下是一些在 Kore 应用中实现 数据模型 的常见方法和建议：
① C 结构体 (struct)：
使用 C 结构体 是最直接和高效的方式来表示数据模型。可以定义 结构体 来存储应用程序中的实体数据，例如用户、文章、产品等。
例如，定义一个 User 结构体：
1
struct User {
2
int id;
3
char *username;
4
char *email;
5
// ... 其他字段
6
};
然后在代码中创建和操作 User 结构体的实例。
② 数据访问层 (Data Access Layer, DAL)：
为了更好地组织代码和分离业务逻辑与数据访问逻辑，可以创建一个 数据访问层。DAL 负责封装所有数据库操作，并提供 API 供业务逻辑层调用。DAL 可以包含用于创建、读取、更新、删除数据模型的函数。
例如，为 User 模型创建一个简单的 DAL：
1
// user.h
2
#ifndef USER_H
3
#define USER_H
4
5
struct User {
6
int id;
7
char *username;
8
char *email;
9
};
10
11
struct User *user_get_by_id(int id);
12
int user_create(struct User *user);
13
int user_update(struct User *user);
14
int user_delete(int id);
15
// ... 其他用户操作函数
16
17
#endif // USER_H
18
19
20
// user.c
21
#include "user.h"
22
#include <kore.h>
23
#include <kore/database.h>
24
25
struct User *
26
user_get_by_id(int id)
27
{
28
struct kore_database *db = kore_database_get("mydb");
29
struct kore_db_result *result = NULL;
30
struct User *user = NULL;
31
32
result = kore_database_query(db, "SELECT id, username, email FROM users WHERE id = $1", id);
33
if (result == NULL || !kore_database_result_next_row(result)) {
34
goto cleanup;
35
}
36
37
user = kore_malloc(sizeof(struct User)); // 分配内存
38
user->id = kore_database_result_get_integer(result, 0);
39
user->username = kore_strdup(kore_database_result_get_string(result, 1)); // 复制字符串
40
user->email = kore_strdup(kore_database_result_get_string(result, 2)); // 复制字符串
41
42
cleanup:
43
if (result != NULL) {
44
kore_database_result_free(result);
45
}
46
return user;
47
}
48
49
// ... user_create, user_update, user_delete 函数的实现
在 处理器 或 中间件 中，可以通过调用 DAL 提供的函数来操作 User 模型的数据。
③ 数据验证 (Data Validation)：
在处理用户输入或从数据库读取数据时，进行 数据验证 非常重要，以确保数据的有效性和完整性。可以在 数据模型 或 DAL 中实现 数据验证 逻辑。
例如，在 user_create() 函数中，可以添加用户名和邮箱格式的验证：
1
int
2
user_create(struct User *user)
3
{
4
if (user == NULL || user->username == NULL || user->email == NULL) {
5
return -1; // 参数错误
6
}
7
8
if (strlen(user->username) < 3 || strlen(user->username) > 50) {
9
return -2; // 用户名长度不合法
10
}
11
12
// 使用正则表达式或自定义函数验证邮箱格式
13
if (!is_valid_email(user->email)) { // is_valid_email() 是一个假设的邮箱验证函数
14
return -3; // 邮箱格式不合法
15
}
16
17
// ... 数据库插入操作
18
return 0; // 成功
19
}
④ 序列化与反序列化 (Serialization and Deserialization)：
当需要将 数据模型 转换为 JSON 或其他格式进行网络传输，或从外部数据源（例如 JSON 文件）加载 数据模型 时，需要实现 序列化 和 反序列化 逻辑。
可以使用 Kore 提供的 JSON API (struct json_value) 或其他 JSON 库 来实现 JSON 序列化 和 反序列化。也可以根据需要实现其他格式（例如 XML, CSV）的 序列化 和 反序列化。
例如，将 User 模型序列化为 JSON 字符串：
1
struct json_value *
2
user_to_json(struct User *user)
3
{
4
struct json_value *json_user = json_object();
5
json_object_push(json_user, "id", json_integer(user->id));
6
json_object_push(json_user, "username", json_string(user->username));
7
json_object_push(json_user, "email", json_string(user->email));
8
return json_user;
9
}
4.3 缓存 (Caching) ⚡️
缓存（Caching）是提高 Web 应用性能的关键技术之一。通过将 frequently accessed data 存储在高速缓存中，可以减少对后端数据源（例如数据库）的访问次数，从而显著提升响应速度和降低延迟。
Kore Web 框架本身没有内置缓存系统，但可以很容易地集成外部缓存系统或使用内存缓存。
① 内存缓存 (In-Memory Cache)：
在 Kore 应用中，可以使用 哈希表（Hash Table）、树（Tree）等数据结构，在内存中实现简单的缓存。可以使用 C 标准库 或第三方库提供的 哈希表 实现，例如 uthash。
例如，使用 uthash 实现一个简单的内存缓存：
1
#include <kore.h>
2
#include <uthash.h> // 引入 uthash 库
3
4
struct cache_entry {
5
char *key; /* key (string) */
6
void *value; /* cached value */
7
UT_hash_handle hh; /* makes this structure hashable */
8
};
9
10
struct cache_entry *cache = NULL; // 全局缓存哈希表
11
12
void
13
cache_set(const char *key, void *value)
14
{
15
struct cache_entry *entry = NULL;
16
HASH_FIND_STR(cache, key, entry); /* check if key already exists */
17
if (entry) {
18
// Key exists, update value (需要考虑旧值的释放)
19
entry->value = value; // 假设 value 是指针，需要考虑内存管理
20
} else {
21
entry = kore_malloc(sizeof(struct cache_entry));
22
entry->key = kore_strdup(key);
23
entry->value = value;
24
HASH_ADD_KEYPTR(hh, cache, entry->key, strlen(entry->key), entry); /* add to hash table */
25
}
26
}
27
28
void *
29
cache_get(const char *key)
30
{
31
struct cache_entry *entry = NULL;
32
HASH_FIND_STR(cache, key, entry); /* find entry by key */
33
if (entry) {
34
return entry->value;
35
} else {
36
return NULL;
37
}
38
}
39
40
void
41
cache_delete(const char *key)
42
{
43
struct cache_entry *entry = NULL;
44
HASH_FIND_STR(cache, key, entry); /* find entry by key */
45
if (entry) {
46
HASH_DEL(cache, entry); /* remove from hash table */
47
kore_free(entry->key);
48
kore_free(entry); // 需要考虑 value 的释放
49
}
50
}
51
52
// ... 在处理器或中间件中使用缓存 API
注意：内存缓存适用于缓存量较小、数据更新频率不高的情况。对于缓存量较大、需要持久化或分布式缓存的场景，建议使用外部缓存系统。
② 外部缓存系统集成：
Kore 应用可以集成各种外部缓存系统，例如 Redis, Memcached 等。可以通过 C 客户端库 连接到这些缓存系统，并使用其提供的 API 进行缓存操作。
例如，集成 Redis：
1
1. 安装 Redis C 客户端库，例如 `hiredis`。
2
2. 在 Kore 代码中引入 `hiredis.h` 头文件。
3
3. 使用 `redisConnect()` 函数连接到 Redis 服务器。
4
4. 使用 `redisCommand()` 或 `redisvCommand()` 函数执行 Redis 命令，例如 `SET`, `GET`, `DEL` 等。
5
5. 使用 `redisReply` 结构体处理 Redis 命令的响应。
6
6. 使用 `redisFree()` 函数关闭 Redis 连接。
示例代码（伪代码，仅供参考）：
1
#include <kore.h>
2
#include <hiredis.h> // 引入 hiredis 库
3
4
redisContext *redis_conn = NULL; // 全局 Redis 连接
5
6
int
7
kore_main(int argc, char *argv[])
8
{
9
// ... 初始化代码
10
11
redis_conn = redisConnect("127.0.0.1", 6379); // 连接到 Redis 服务器
12
if (redis_conn == NULL || redis_conn->err) {
13
kore_log(LOG_ERR, "Redis connection failed: %s", redis_conn ? redis_conn->errstr : "Unknown error");
14
return (KORE_RESULT_ERROR);
15
}
16
17
// ... 注册路由和中间件
18
19
return (KORE_RESULT_OK);
20
}
21
22
void
23
kore_worker_shutdown()
24
{
25
if (redis_conn) {
26
redisFree(redis_conn); // 关闭 Redis 连接
27
redis_conn = NULL;
28
}
29
}
30
31
void *
32
get_data_from_cache_or_db(const char *key)
33
{
34
redisReply *reply;
35
void *data = NULL;
36
37
reply = redisCommand(redis_conn, "GET %s", key); // 从 Redis 缓存获取数据
38
if (reply != NULL && reply->type == REDIS_REPLY_STRING) {
39
data = kore_strdup(reply->str); // 复制缓存数据
40
freeReplyObject(reply);
41
return data; // 返回缓存数据
42
}
43
freeReplyObject(reply);
44
45
// 如果缓存未命中，从数据库获取数据
46
data = get_data_from_database(key);
47
if (data != NULL) {
48
reply = redisCommand(redis_conn, "SET %s %s", key, (char *)data); // 将数据存入缓存
49
freeReplyObject(reply);
50
}
51
52
return data;
53
}
③ 缓存策略：
选择合适的 缓存策略 对于提高缓存效率至关重要。常见的缓存策略包括：
1
* **Cache-Aside (旁路缓存)**：应用程序先从缓存中读取数据，如果缓存未命中，则从数据库读取数据，并将数据写入缓存。这是最常用的缓存策略。
2
* **Read-Through (读穿透)**：应用程序只与缓存交互，缓存负责从数据库读取数据并在缓存未命中时自动加载数据。
3
* **Write-Through (写穿透)**：每次数据更新都同时写入缓存和数据库，保持数据一致性。
4
* **Write-Back (写回)**：数据更新只写入缓存，缓存定期或在特定条件下将数据写回数据库，性能较高，但数据一致性风险较高。
根据应用场景和需求，选择合适的缓存系统和缓存策略，可以有效地提高 Kore Web 应用的性能和可扩展性。
4.4 文件上传与处理 📂
Kore Web 框架支持 文件上传 功能，允许客户端通过 HTTP POST 请求上传文件。Kore 能够处理 multipart/form-data 类型的请求，并提供 API 来访问上传的文件数据。
① 处理 multipart/form-data 请求：
当客户端使用 multipart/form-data 编码方式上传文件时，Kore 会自动解析请求体，并将上传的文件信息存储在 struct http_request 对象中。
可以使用以下 API 获取上传的文件信息：
1
* `http_request_file_count(req)`：获取上传的文件数量。
2
* `http_request_file_name(req, index)`：根据索引 `index` 获取上传文件的字段名 (form-data 中的 name 属性)。
3
* `http_request_file_filename(req, index)`：根据索引 `index` 获取上传文件的原始文件名。
4
* `http_request_file_content_type(req, index)`：根据索引 `index` 获取上传文件的 **Content-Type**。
5
* `http_request_file_data(req, index)`：根据索引 `index` 获取上传文件的内存数据指针。
6
* `http_request_file_length(req, index)`：根据索引 `index` 获取上传文件的长度。
7
* `http_request_file_save(req, index, path)`：将索引 `index` 的上传文件保存到指定路径 `path` 的文件中。
② 文件上传处理示例：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <stdio.h> // for fprintf
4
5
int upload_handler(struct http_request *);
6
7
int
8
upload_handler(struct http_request *req)
9
{
10
int file_count = http_request_file_count(req);
11
if (file_count == 0) {
12
http_response(req, 400, "No file uploaded", 16);
13
return (KORE_RESULT_ERROR);
14
}
15
16
for (int i = 0; i < file_count; i++) {
17
const char *field_name = http_request_file_name(req, i);
18
const char *file_name = http_request_file_filename(req, i);
19
const char *content_type = http_request_file_content_type(req, i);
20
void *file_data = http_request_file_data(req, i);
21
size_t file_length = http_request_file_length(req, i);
22
23
kore_log(LOG_INFO, "Uploaded file %d:", i + 1);
24
kore_log(LOG_INFO, " Field Name: %s", field_name);
25
kore_log(LOG_INFO, " File Name: %s", file_name);
26
kore_log(LOG_INFO, " Content-Type: %s", content_type);
27
kore_log(LOG_INFO, " File Length: %zu bytes", file_length);
28
29
// 将文件保存到服务器本地
30
char save_path[256];
31
snprintf(save_path, sizeof(save_path), "/tmp/uploaded_%s", file_name); // 临时保存路径
32
if (http_request_file_save(req, i, save_path) == KORE_RESULT_OK) {
33
kore_log(LOG_INFO, " File saved to: %s", save_path);
34
} else {
35
kore_log(LOG_ERR, " Failed to save file to: %s", save_path);
36
}
37
38
// 或者直接处理文件数据 (例如，图片处理、文件内容分析等)
39
// ...
40
}
41
42
http_response(req, 200, "File uploaded successfully", 26);
43
return (KORE_RESULT_OK);
44
}
45
46
int
47
kore_main(int argc, char *argv[])
48
{
49
kore_http_handler_add("/upload", upload_handler);
50
return (KORE_RESULT_OK);
51
}
HTML 表单示例 (用于客户端上传文件)：
1
<form action="/upload" method="post" enctype="multipart/form-data">
2
<input type="file" name="myfile">
3
<input type="submit" value="Upload File">
4
</form>
③ 文件存储与处理：
上传文件后，可以选择将其保存到服务器本地文件系统、云存储服务（例如 Amazon S3, Azure Blob Storage, Google Cloud Storage）或数据库中。
1
* **本地文件系统存储**：使用 `http_request_file_save()` 函数可以将上传文件保存到服务器本地文件系统的指定路径。需要注意文件存储路径的安全性、磁盘空间管理和文件访问权限控制。
2
* **云存储服务**：集成云存储服务的 **SDK** 或 **API**，可以将上传文件直接上传到云存储服务，例如使用 AWS SDK for C++ 或 libcurl 调用 S3 API。
3
* **数据库存储**：可以将文件内容作为 **BLOB** (Binary Large Object) 类型存储在数据库中。适用于存储小文件或需要与数据库事务保持一致性的场景。
④ 文件上传安全：
在处理文件上传时，需要注意以下安全问题：
1
* **文件类型验证**：验证上传文件的 **Content-Type** 和文件扩展名，防止上传恶意文件（例如，WebShell 脚本）。
2
* **文件大小限制**：限制上传文件的最大大小，防止 **拒绝服务攻击**（Denial of Service, DoS）。可以使用 `kore.conf` 中的 `max_request_body` 配置项限制整个请求体的最大大小。
3
* **文件名安全**：对上传文件名进行安全处理，防止文件名包含恶意字符或路径遍历漏洞。
4
* **文件存储安全**：确保文件存储路径的安全性和访问权限控制，防止未授权访问或恶意修改上传文件。
Chapter 4 深入探讨了 Kore Web 框架中数据处理与存储相关的 API 和技术，包括数据库集成、数据模型、缓存和文件上传处理。掌握这些内容可以帮助开发者构建功能完善、性能高效的 Kore Web 应用。在接下来的章节中，我们将继续学习 Kore 的异步与并发处理能力，以及应用开发实践。
5. chapter 5： Kore API 详解 - 异步与并发 🚦
5.1 异步编程 (Asynchronous Programming) ⏳
异步编程（Asynchronous Programming）是一种重要的编程范式，尤其在高性能网络应用中至关重要。它允许程序在执行耗时操作（例如 I/O 操作，如网络请求、数据库查询、文件读写）时，不必阻塞等待操作完成，而是可以继续执行其他任务。当耗时操作完成后，程序会得到通知，并继续处理操作结果。异步编程能够显著提高程序的并发性和响应性。
Kore Web 框架从底层就采用了 异步非阻塞 I/O 模型，这使得构建高性能异步应用成为可能。Kore 提供了多种 API 来支持异步编程，主要体现在以下几个方面：
① 异步 HTTP 请求：
⚝ http_client_request_async()：用于发起 异步 HTTP 客户端请求。与同步请求不同，异步请求不会阻塞当前线程，请求的结果会通过回调函数返回。
http_client_request_async() 函数原型：
1
int http_client_request_async(struct http_client *client, struct http_request *req,
2
void (*callback)(struct http_client *, void *), void *arg, int timeout);
参数说明：
1
* `client`：指向 `struct http_client` 对象的指针，表示 HTTP 客户端连接。
2
* `req`：指向 `struct http_request` 对象的指针，表示要发送的 HTTP 请求。
3
* `callback`：回调函数，当请求完成时被调用。回调函数原型为 `void (*callback)(struct http_client *, void *)`，其中第一个参数是 `http_client` 对象，第二个参数是 `arg`。
4
* `arg`：用户自定义参数，会传递给回调函数。
5
* `timeout`：请求超时时间，单位毫秒。
回调函数原型：
1
void callback_function(struct http_client *client, void *arg) {
2
struct http_request *response_req = client->request; // 获取响应请求对象
3
if (client->error) {
4
kore_log(LOG_ERR, "HTTP client error: %d", client->error);
5
// 处理错误
6
} else if (response_req->status != 200) {
7
kore_log(LOG_WARNING, "HTTP request failed with status: %d", response_req->status);
8
// 处理非 200 状态码
9
} else {
10
// 请求成功，处理响应
11
void *body_data = response_req->http_body;
12
size_t body_len = response_req->http_body_len;
13
// ... 处理响应体数据
14
}
15
// ... 其他处理
16
http_client_free(client); // 释放 http_client 对象
17
}
发起异步 HTTP GET 请求的示例：
1
#include <kore.h>
2
#include <kore/http.h>
3
4
void async_http_callback(struct http_client *, void *);
5
6
int
7
async_http_request_handler(struct http_request *req)
8
{
9
struct http_client *client;
10
struct http_request *client_req;
11
12
client = http_client_alloc();
13
http_client_set_url(client, "http://example.com/api/data"); // 设置请求 URL
14
15
client_req = http_request_new(HTTP_METHOD_GET, "/api/data"); // 创建请求对象
16
http_client_request_async(client, client_req, async_http_callback, NULL, 5000); // 发起异步请求，超时 5 秒
17
18
http_response(req, 202, "Async request initiated", 23); // 返回 202 Accepted，表示请求已接受，异步处理中
19
return (KORE_RESULT_OK);
20
}
21
22
void
23
async_http_callback(struct http_client *client, void *arg)
24
{
25
struct http_request *response_req = client->request;
26
27
if (client->error) {
28
kore_log(LOG_ERR, "Async HTTP request error: %d", client->error);
29
} else if (response_req->status != 200) {
30
kore_log(LOG_WARNING, "Async HTTP request failed with status: %d", response_req->status);
31
} else {
32
kore_log(LOG_INFO, "Async HTTP request success, response body length: %zu", response_req->http_body_len);
33
// 处理响应数据
34
// ...
35
}
36
http_client_free(client); // 释放 http_client 对象
37
}
38
39
int
40
kore_main(int argc, char *argv[])
41
{
42
kore_http_handler_add("/async-http", async_http_request_handler);
43
return (KORE_RESULT_OK);
44
}
② 异步数据库查询：
⚝ kore_database_query_async()：用于 异步执行数据库查询。查询结果通过回调函数返回，不会阻塞当前请求处理线程。
kore_database_query_async() 函数原型：
1
int kore_database_query_async(struct kore_database *db, const char *query,
2
void (*callback)(struct kore_database *, void *, struct kore_db_result *),
3
void *arg, ...);
参数说明：
1
* `db`：指向 `struct kore_database` 对象的指针，表示数据库连接。
2
* `query`：SQL 查询语句，可以使用参数占位符 `$1`, `$2`, ...。
3
* `callback`：回调函数，当查询完成时被调用。回调函数原型为 `void (*callback)(struct kore_database *, void *, struct kore_db_result *)`，其中第一个参数是 `db` 对象，第二个参数是 `arg`，第三个参数是查询结果 `struct kore_db_result` 对象。
4
* `arg`：用户自定义参数，会传递给回调函数。
5
* `...`：可变参数列表，用于传递 SQL 查询参数。
回调函数原型：
1
void callback_function(struct kore_database *db, void *arg, struct kore_db_result *result) {
2
if (result == NULL) {
3
kore_log(LOG_ERR, "Async database query failed: %s", kore_database_error(db));
4
// 处理错误
5
} else {
6
// 查询成功，处理查询结果
7
while (kore_database_result_next_row(result)) {
8
// ... 处理每一行数据
9
}
10
kore_database_result_free(result); // 释放结果集
11
}
12
// ... 其他处理
13
}
发起异步数据库查询的示例：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <kore/database.h>
4
5
void async_db_callback(struct kore_database *, void *, struct kore_db_result *);
6
7
int
8
async_db_query_handler(struct http_request *req)
9
{
10
struct kore_database *db;
11
12
db = kore_database_get("mydb"); // 获取数据库连接
13
if (db == NULL) {
14
http_response_error(req, 500);
15
return (KORE_RESULT_ERROR);
16
}
17
18
kore_database_query_async(db, "SELECT id, username FROM users WHERE active = $1",
19
async_db_callback, req, 1); // 异步查询 active 用户
20
21
http_response(req, 202, "Async DB query initiated", 25); // 返回 202 Accepted
22
return (KORE_RESULT_OK);
23
}
24
25
void
26
async_db_callback(struct kore_database *db, void *arg, struct kore_db_result *result)
27
{
28
struct http_request *req = (struct http_request *)arg;
29
30
if (result == NULL) {
31
kore_log(LOG_ERR, "Async database query failed: %s", kore_database_error(db));
32
http_response_error(req, 500); // 异步处理中发生错误，需要考虑如何返回错误给客户端，这里简单处理为返回 500
33
} else {
34
http_response_header(req, "Content-Type", "text/plain");
35
http_response_open(req, 200, "text/plain");
36
37
while (kore_database_result_next_row(result)) {
38
int id = kore_database_result_get_integer(result, 0);
39
const char *username = kore_database_result_get_string(result, 1);
40
char buffer[256];
41
snprintf(buffer, sizeof(buffer), "User ID: %d, Username: %s\n", id, username);
42
http_response_stream(req, buffer, strlen(buffer));
43
}
44
http_response_close(req);
45
kore_database_result_free(result); // 释放结果集
46
}
47
// 注意：在异步回调函数中，不能直接使用原始的 http_request 对象 req 来发送完整响应，
48
// 因为原始请求处理函数可能已经返回。需要在回调函数中构建完整的响应并发送。
49
// 示例中简单地在回调函数中构建并发送了响应。
50
}
51
52
int
53
kore_main(int argc, char *argv[])
54
{
55
kore_http_handler_add("/async-db", async_db_query_handler);
56
return (KORE_RESULT_OK);
57
}
注意：在异步回调函数中处理响应时，需要小心处理 struct http_request 对象。通常情况下，原始的请求处理函数在发起异步操作后就会返回，因此在回调函数中构建响应时，可能需要确保请求上下文仍然有效，或者使用其他机制将响应数据发送回客户端。在上面的 async_db_callback 示例中，为了简化示例，直接在回调函数中构建并发送了响应。在更复杂的场景中，可能需要更精细的异步响应管理。
5.2 并发处理 (Concurrency) 👯
并发处理（Concurrency）是指程序同时处理多个任务的能力。在 Web 应用中，并发处理通常用于处理多个客户端请求，提高服务器的吞吐量和响应速度。Kore Web 框架通过 多进程模型 和 异步非阻塞 I/O 来实现高效的并发处理。
① 多进程模型：
Kore 默认采用 多进程模型 来处理并发请求。在 kore.conf 配置文件中，可以通过 server.http.processes 配置项设置工作进程数。Kore 会启动多个工作进程，每个进程独立监听端口并处理客户端请求。操作系统负责将客户端连接分配给不同的工作进程，实现负载均衡。
多进程模型的优势在于进程之间的隔离性好，一个进程崩溃不会影响其他进程。同时，可以充分利用多核 CPU 的性能。
配置工作进程数示例 (kore.conf)：
1
server "http" {
2
listen = "0.0.0.0:8888"
3
processes = 4 # 设置 4 个工作进程
4
}
② 异步非阻塞 I/O：
在每个工作进程内部，Kore 使用 异步非阻塞 I/O 模型来处理多个连接。当一个连接上有 I/O 操作（例如接收请求数据、发送响应数据）时，进程不会阻塞等待操作完成，而是可以继续处理其他连接。当 I/O 操作准备就绪时，操作系统会通知进程，进程再来处理 I/O 事件。
Kore 使用 epoll (Linux), kqueue (BSD) 等高效的 I/O 多路复用技术来实现异步非阻塞 I/O。这使得每个工作进程可以高效地处理大量并发连接，而无需为每个连接创建独立的线程或进程，从而降低了资源消耗，提高了并发性能。
③ 事件驱动编程：
Kore 的异步非阻塞 I/O 模型是基于 事件驱动 的。Kore 核心循环不断监听各种事件，例如网络连接事件、HTTP 请求事件、定时器事件等。当事件发生时，Kore 会调用相应的事件处理函数来处理事件。这种 事件驱动 的架构使得 Kore 能够高效地响应各种事件，并保持高并发性能。
④ 协程 (Coroutines) (可选)：
虽然 Kore 默认使用多进程和异步非阻塞 I/O 实现并发，但在某些特定场景下，协程（Coroutines）也可以作为一种补充的并发模型。协程 是一种轻量级的用户态线程，可以在单个进程或线程内实现并发执行。
Kore 本身没有内置协程支持，但可以考虑集成第三方协程库，例如 libtask 或 libmill。使用协程可以进一步提高单进程的并发能力，并简化异步编程的复杂性。然而，协程的引入也会增加代码的复杂性和维护成本，需要根据具体需求权衡利弊。
5.3 WebSocket 支持 💬
WebSocket 是一种在客户端和服务器之间建立 持久连接 的协议，用于实现 实时双向通信。Kore Web 框架原生支持 WebSocket 协议，可以方便地构建实时 Web 应用，例如在线聊天、实时数据推送、多人在线游戏等。
Kore WebSocket 支持的主要 API 包括：
① WebSocket 处理器注册：
⚝ kore_websocket_handler_add()：用于注册 WebSocket 处理器，将指定的路径与 WebSocket 处理函数关联起来。当客户端发起 WebSocket 连接 请求到该路径时，Kore 会调用相应的处理函数。
kore_websocket_handler_add() 函数原型：
1
void kore_websocket_handler_add(const char *path, int (*handler)(struct http_request *));
参数说明：
1
* `path`：WebSocket 连接路径，例如 `"/ws"`, `"/chat"`.
2
* `handler`：WebSocket 处理函数，当客户端发起 WebSocket 连接请求时被调用。处理函数原型为 `int (*handler)(struct http_request *)`。
WebSocket 处理函数原型：
1
int websocket_handler(struct http_request *req) {
2
// 检查是否是 WebSocket 升级请求
3
if (!http_request_is_websocket(req)) {
4
http_response_error(req, 400); // Bad Request，不是 WebSocket 请求
5
return (KORE_RESULT_ERROR);
6
}
7
8
// 执行 WebSocket 握手，建立 WebSocket 连接
9
int ret = http_websocket_handshake(req, "my-websocket-protocol"); // 可选的子协议
10
if (ret != KORE_RESULT_OK) {
11
http_response_error(req, 500); // Internal Server Error，握手失败
12
return (KORE_RESULT_ERROR);
13
}
14
15
// 获取 WebSocket 连接对象
16
struct websocket *ws = req->websocket;
17
// 设置 WebSocket 连接的用户数据 (可选)
18
ws->user_data = ...;
19
20
// 设置 WebSocket 消息接收回调函数
21
websocket_set_message_callback(ws, websocket_message_callback);
22
// 设置 WebSocket 关闭回调函数 (可选)
23
websocket_set_close_callback(ws, websocket_close_callback);
24
25
kore_log(LOG_INFO, "WebSocket connection established for path: %s", req->path);
26
return (KORE_RESULT_OK);
27
}
② WebSocket 消息发送：
⚝ websocket_send_message()：用于向指定的 WebSocket 连接发送消息。可以发送文本消息或二进制消息。
websocket_send_message() 函数原型：
1
int websocket_send_message(struct websocket *ws, uint8_t op, void *data, size_t len);
参数说明：
1
* `ws`：指向 `struct websocket` 对象的指针，表示 WebSocket 连接。
2
* `op`：WebSocket 操作码，用于指定消息类型。
3
* `WEBSOCKET_OP_TEXT`：文本消息。
4
* `WEBSOCKET_OP_BINARY`：二进制消息。
5
* `data`：消息数据指针。
6
* `len`：消息数据长度。
发送文本消息示例：
1
int
2
websocket_message_callback(struct websocket *ws, uint8_t op, void *data, size_t len)
3
{
4
if (op == WEBSOCKET_OP_TEXT) {
5
kore_log(LOG_INFO, "Received WebSocket message: %.*s", (int)len, (char *)data);
6
// Echo back the message
7
websocket_send_message(ws, WEBSOCKET_OP_TEXT, data, len);
8
}
9
return (KORE_RESULT_OK);
10
}
③ WebSocket 连接关闭：
⚝ websocket_close()：用于关闭指定的 WebSocket 连接。可以由服务器主动关闭连接，也可以响应客户端的关闭请求。
websocket_close() 函数原型：
1
void websocket_close(struct websocket *ws);
在 WebSocket 关闭回调函数中处理连接关闭事件：
1
void
2
websocket_close_callback(struct websocket *ws)
3
{
4
kore_log(LOG_INFO, "WebSocket connection closed");
5
// 清理 WebSocket 连接相关的资源，例如释放 ws->user_data
6
// ...
7
}
④ WebSocket 广播 (Broadcast)：
Kore 没有内置 WebSocket 广播功能，但可以自行实现。一种常见的实现方式是维护一个 WebSocket 连接列表，当需要广播消息时，遍历列表，向每个连接发送消息。
示例代码（伪代码，仅供参考）：
1
// 全局 WebSocket 连接列表 (需要线程安全保护，如果多进程/多线程环境)
2
struct websocket_list_entry {
3
struct websocket *ws;
4
UT_list_handle hh;
5
};
6
struct websocket_list_entry *websocket_connections = NULL;
7
8
void
9
add_websocket_connection(struct websocket *ws) {
10
struct websocket_list_entry *entry = kore_malloc(sizeof(struct websocket_list_entry));
11
entry->ws = ws;
12
UT_LIST_ADD(websocket_connections, entry);
13
}
14
15
void
16
remove_websocket_connection(struct websocket *ws) {
17
struct websocket_list_entry *entry = NULL, *tmp = NULL;
18
UT_LIST_FOREACH_SAFE(websocket_connections, entry, tmp) {
19
if (entry->ws == ws) {
20
UT_LIST_DELETE(websocket_connections, entry);
21
kore_free(entry);
22
break;
23
}
24
}
25
}
26
27
void
28
broadcast_message(uint8_t op, void *data, size_t len) {
29
struct websocket_list_entry *entry = NULL, *tmp = NULL;
30
UT_LIST_FOREACH_SAFE(websocket_connections, entry, tmp) {
31
websocket_send_message(entry->ws, op, data, len);
32
}
33
}
34
35
int
36
websocket_handler(struct http_request *req) {
37
// ... WebSocket 握手和连接建立
38
39
struct websocket *ws = req->websocket;
40
add_websocket_connection(ws); // 将新连接添加到连接列表
41
websocket_set_close_callback(ws, websocket_close_callback); // 设置关闭回调，在回调中移除连接
42
return (KORE_RESULT_OK);
43
}
44
45
void
46
websocket_close_callback(struct websocket *ws) {
47
remove_websocket_connection(ws); // 从连接列表中移除已关闭的连接
48
// ...
49
}
50
51
// ... 在其他地方调用 broadcast_message() 函数广播消息
52
broadcast_message(WEBSOCKET_OP_TEXT, "Server message", strlen("Server message"));
5.4 事件驱动编程 (Event-Driven Programming) 🕹️
事件驱动编程（Event-Driven Programming）是一种编程范式，程序的执行流程由事件的发生驱动。程序主要负责监听和响应各种事件，而不是按照预定的顺序执行代码。Kore Web 框架的核心架构就是 事件驱动 的。
Kore 的事件驱动机制主要体现在以下几个方面：
① 事件循环 (Event Loop)：
Kore 核心运行一个 事件循环（Event Loop），不断监听和处理各种事件。事件来源包括：
1
* **网络事件**：新的客户端连接请求、已连接的 socket 上的数据到达事件、连接关闭事件等。
2
* **定时器事件**：由 `kore_timer_add()` 函数添加的定时器到期事件。
3
* **信号事件**：操作系统信号事件，例如 `SIGINT`, `SIGTERM` 等。
4
* **文件 I/O 事件** (在某些情况下，例如使用 `kore_platform_event_wait()` 监听文件描述符)。
5
* **用户自定义事件** (可以通过 `kore_event_create()` 和 `kore_event_signal()` 创建和触发)。
② 事件处理器 (Event Handlers)：
对于每种类型的事件，Kore 都有相应的 事件处理器（Event Handler）函数。当事件循环监听到事件发生时，会调用相应的事件处理器函数来处理事件。例如：
1
* **HTTP 请求处理器**：处理 HTTP 请求事件，例如路由匹配、中间件执行、处理器执行等。
2
* **WebSocket 消息处理器**：处理 WebSocket 消息到达事件。
3
* **定时器事件处理器**：处理定时器到期事件。
4
* **信号处理器**：处理操作系统信号事件。
开发者可以通过注册 HTTP 处理器、WebSocket 处理器、定时器 等来扩展 Kore 的事件处理能力，实现自定义的事件驱动逻辑。
③ 定时器 (Timers)：
⚝ kore_timer_add()：用于添加 定时器，在指定的延迟时间后触发事件。可以设置定时器为单次触发或周期性触发。
kore_timer_add() 函数原型：
1
int kore_timer_add(void (*callback)(void *), void *arg, int timeout, int repeat);
参数说明：
1
* `callback`：定时器回调函数，当定时器到期时被调用。回调函数原型为 `void (*callback)(void *)`，参数为 `arg`。
2
* `arg`：用户自定义参数，会传递给回调函数。
3
* `timeout`：定时器延迟时间，单位毫秒。
4
* `repeat`：是否重复触发定时器。
5
* `KORE_TIMER_ONESHOT`：单次触发。
6
* `KORE_TIMER_REPEAT`：周期性触发，每隔 `timeout` 毫秒触发一次。
添加单次定时器示例：
1
#include <kore.h>
2
3
void timer_callback(void *);
4
5
int
6
kore_main(int argc, char *argv[])
7
{
8
kore_timer_add(timer_callback, NULL, 5000, KORE_TIMER_ONESHOT); // 5 秒后触发 timer_callback
9
return (KORE_RESULT_OK);
10
}
11
12
void
13
timer_callback(void *arg)
14
{
15
kore_log(LOG_INFO, "Timer expired!");
16
// 执行定时任务
17
// ...
18
}
添加周期性定时器示例：
1
#include <kore.h>
2
3
void periodic_timer_callback(void *);
4
5
int
6
kore_main(int argc, char *argv[])
7
{
8
kore_timer_add(periodic_timer_callback, NULL, 1000, KORE_TIMER_REPEAT); // 每 1 秒触发 periodic_timer_callback
9
return (KORE_RESULT_OK);
10
}
11
12
void
13
periodic_timer_callback(void *arg)
14
{
15
static int count = 0;
16
count++;
17
kore_log(LOG_INFO, "Periodic timer callback, count: %d", count);
18
// 执行周期性任务
19
// ...
20
if (count >= 10) {
21
kore_log(LOG_INFO, "Stopping periodic timer");
22
kore_timer_remove(periodic_timer_callback, NULL); // 停止周期性定时器
23
}
24
}
④ 用户自定义事件：
⚝ kore_event_create()：创建用户自定义事件对象。
⚝ kore_event_signal()：触发用户自定义事件。
⚝ kore_platform_event_wait()：等待事件发生。
用户自定义事件可以用于在 Kore 应用中实现更复杂的异步协作和事件通知机制。
Chapter 5 深入探讨了 Kore Web 框架在异步与并发处理方面的 API 和技术，包括异步编程、并发处理、WebSocket 支持和事件驱动编程。掌握这些内容可以帮助开发者构建高性能、高并发、实时的 Kore Web 应用。在接下来的章节中，我们将学习 Kore 应用开发的实践技巧和最佳实践。
6. chapter 6： Kore 应用开发实践 💻
6.1 项目结构与组织 🏗️
良好的 项目结构（Project Structure）和代码组织是构建可维护、可扩展 Kore Web 应用的基础。一个清晰的项目结构能够提高开发效率，降低维护成本，并方便团队协作。
以下是一些建议的 Kore 项目结构和组织方式：
① 基本目录结构：
一个典型的 Kore 项目目录结构可以如下所示：
1
project-root/
2
├── src/ # 源代码目录
3
│ ├── handlers/ # HTTP 请求处理器
4
│ │ ├── home.c
5
│ │ ├── users.c
6
│ │ └── ...
7
│ ├── middleware/ # 中间件
8
│ │ ├── logger.c
9
│ │ ├── auth.c
10
│ │ └── ...
11
│ ├── models/ # 数据模型和数据访问层 (DAL)
12
│ │ ├── user.c
13
│ │ ├── article.c
14
│ │ └── ...
15
│ ├── templates/ # 模板文件
16
│ │ ├── index.html
17
│ │ ├── user_list.html
18
│ │ └── ...
19
│ ├── static/ # 静态资源文件 (CSS, JavaScript, images)
20
│ │ ├── css/
21
│ │ ├── js/
22
│ │ ├── images/
23
│ │ └── ...
24
│ ├── utils/ # 通用工具函数和模块
25
│ │ ├── string_utils.c
26
│ │ ├── date_utils.c
27
│ │ └── ...
28
│ └── kore_main.c # 主程序入口文件
29
├── config/ # 配置文件目录
30
│ └── kore.conf
31
├── data/ # 数据文件目录 (例如 SQLite 数据库文件)
32
│ └── app.db
33
├── log/ # 日志文件目录
34
│ └── app.log
35
├── Makefile # 构建脚本
36
└── README.md # 项目说明文件
这个结构将不同类型的代码和资源文件组织在不同的目录中，使得项目结构清晰易懂。
② 模块化开发（Modular Development）：
将应用功能划分为独立的 模块（Module），每个模块负责特定的业务功能。例如，用户管理模块、文章管理模块、权限管理模块等。每个模块可以包含自己的 处理器、中间件、模型、模板 和 静态资源。
模块化开发可以提高代码的 可重用性（Reusability）、可维护性（Maintainability）和 可测试性（Testability）。
③ 代码组织原则：
⚝ 单一职责原则（Single Responsibility Principle, SRP）：每个模块、类、函数只负责一个明确的职责。
⚝ 开闭原则（Open/Closed Principle, OCP）：模块、类应该对扩展开放，对修改关闭。即在不修改现有代码的情况下，可以扩展其功能。
⚝ 依赖倒置原则（Dependency Inversion Principle, DIP）：高层模块不应该依赖低层模块，两者都应该依赖抽象；抽象不应该依赖细节，细节应该依赖抽象。
⚝ KISS 原则（Keep It Simple, Stupid）：保持代码简洁易懂。
⚝ DRY 原则（Don't Repeat Yourself）：避免代码重复。
④ 命名规范（Naming Conventions）：
采用一致的 命名规范 可以提高代码的可读性。建议的命名规范包括：
⚝ 文件名：使用小写字母，单词之间用下划线 _ 分隔，例如 user_handler.c, string_utils.c。
⚝ 函数名：使用小写字母，单词之间用下划线 _ 分隔，动词开头，例如 get_user_by_id(), validate_email()。
⚝ 变量名：使用小写字母，单词之间用下划线 _ 分隔，例如 user_id, request_body。
⚝ 宏定义：使用大写字母，单词之间用下划线 _ 分隔，例如 MAX_USERNAME_LENGTH, DEFAULT_TIMEOUT。
⚝ 结构体名 和 枚举类型名：使用 PascalCase 命名法，例如 HttpRequest, HttpMethod。
⑤ 构建脚本 (Makefile)：
使用 Makefile 管理项目的构建过程，包括编译、链接、安装等步骤。一个基本的 Makefile 示例如下：
1
# Makefile
2
3
PROG = my-kore-app
4
SRCS = src/kore_main.c src/handlers/*.c src/middleware/*.c src/models/*.c src/utils/*.c
5
OBJS = $(SRCS:.c=.o)
6
CFLAGS = -Wall -Wextra -Werror -g -I/usr/local/include # 根据 Kore 安装路径调整 include 路径
7
LIBS = -lkore -lssl -lcrypto -lpcre -lz # 根据 Kore 依赖调整库
8
9
$(PROG): $(OBJS)
10
$(CC) $(CFLAGS) -o $(PROG) $(OBJS) $(LIBS)
11
12
%.o: %.c
13
$(CC) $(CFLAGS) -c $< -o $@
14
15
install: $(PROG)
16
sudo install -d /usr/local/bin
17
sudo install $(PROG) /usr/local/bin/
18
19
clean:
20
rm -f $(PROG) $(OBJS)
21
22
.PHONY: install clean
根据项目需求，可以进一步完善 Makefile，例如添加配置文件复制、静态资源复制、数据库初始化等步骤。
6.2 模板引擎 (Template Engine) 📄
模板引擎（Template Engine）用于将动态数据和静态模板文件结合起来，生成最终的 HTML 或其他格式的输出。在 Web 应用开发中，模板引擎可以将 视图（View）逻辑与 业务逻辑 分离，提高代码的可维护性和可读性。
Kore Web 框架本身没有内置模板引擎，但可以很容易地集成第三方 C 语言 模板引擎库，例如：
① Mustache.c：https://github.com/hoxton/mustache.c
Mustache 是一种流行的逻辑less模板语言，mustache.c 是一个 C 语言 实现的 Mustache 模板引擎库。
② Handlebars.c：https://github.com/daaku/handlebars.c
Handlebars 是 Mustache 的扩展，提供了更强大的功能，handlebars.c 是一个 C 语言 实现的 Handlebars 模板引擎库。
③ Pug (formerly Jade)：https://pugjs.org/api/ (需要 C 语言 binding)
Pug (原 Jade) 是一种简洁的模板引擎，虽然 Pug 主要用于 JavaScript，但也有一些 C 语言 binding 可用。
6.2.1 集成 Mustache.c 示例
以下示例展示了如何在 Kore 应用中集成 mustache.c 模板引擎。
(1). 安装 mustache.c：
根据 mustache.c 的文档，下载源代码并编译安装。通常的安装步骤如下：
1
git clone https://github.com/hoxton/mustache.c.git
2
cd mustache.c
3
make
4
sudo make install
(2). 在 Kore 项目中引入 mustache.c：
在 Kore 项目的 Makefile 中，添加 mustache.c 的 include 路径和库链接。例如：
1
CFLAGS += -I/usr/local/include # mustache.h 安装路径
2
LIBS += -lmustache # libmustache.so 或 libmustache.a
(3). 创建模板处理函数：
创建一个函数，用于加载模板文件，渲染模板，并将结果发送到 HTTP 响应。
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <mustache.h> // 引入 mustache.h
4
5
int
6
render_template(struct http_request *req, const char *template_path, struct json_value *data)
7
{
8
char *template_content;
9
long template_size;
10
11
// 读取模板文件内容
12
template_content = kore_file_read(template_path, &template_size);
13
if (template_content == NULL) {
14
kore_log(LOG_ERR, "Failed to read template file: %s", template_path);
15
http_response_error(req, 500);
16
return (KORE_RESULT_ERROR);
17
}
18
19
// 渲染模板
20
char *output = mustache_render(template_content, data);
21
kore_free(template_content); // 释放模板文件内容
22
23
if (output == NULL) {
24
kore_log(LOG_ERR, "Failed to render template: %s", template_path);
25
http_response_error(req, 500);
26
return (KORE_RESULT_ERROR);
27
}
28
29
// 发送响应
30
http_response_header(req, "Content-Type", "text/html");
31
http_response(req, 200, output, strlen(output));
32
free(output); // 释放 mustache_render 分配的内存
33
34
return (KORE_RESULT_OK);
35
}
(4). 在处理器中使用模板引擎：
在 HTTP 请求处理器中，调用 render_template() 函数渲染模板并发送响应。
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <json.h> // for json_value, json_object, json_string, etc.
4
5
int index_handler(struct http_request *);
6
int render_template(struct http_request *req, const char *template_path, struct json_value *data); // 声明模板处理函数
7
8
int
9
index_handler(struct http_request *req)
10
{
11
struct json_value *data = json_object();
12
json_object_push(data, "title", json_string("Kore Web Framework Example"));
13
json_object_push(data, "message", json_string("Hello from Kore with Mustache!"));
14
15
return render_template(req, "src/templates/index.html", data); // 渲染 index.html 模板
16
}
17
18
int
19
kore_main(int argc, char *argv[])
20
{
21
kore_http_handler_add("/", index_handler);
22
return (KORE_RESULT_OK);
23
}
(5). 创建模板文件 (index.html)：
在 src/templates/ 目录下创建 index.html 模板文件。
1
<!DOCTYPE html>
2
<html>
3
<head>
4
<title>{{title}}</title>
5
</head>
6
<body>
7
<h1>{{message}}</h1>
8
</body>
9
</html>
模板文件中使用 {{key}} 语法表示占位符，这些占位符会被 render_template() 函数传入的 data JSON 对象中的值替换。
通过以上步骤，就成功地在 Kore 应用中集成了 mustache.c 模板引擎，可以使用模板文件和动态数据生成 HTML 响应。可以根据项目需求选择其他模板引擎，并按照类似的步骤进行集成。
6.3 表单处理与验证 (Form Handling and Validation) ✅
表单处理（Form Handling）和 表单验证（Form Validation）是 Web 应用开发中常见的任务。Kore Web 框架提供了 API 来处理 HTTP POST 请求提交的表单数据，并可以实现自定义的表单验证逻辑。
① 获取表单数据：
当客户端通过 HTTP POST 请求提交表单数据时，Kore 可以解析请求体，并将表单数据存储在 struct http_request 对象中。可以使用以下 API 获取表单数据：
⚝ http_request_body_form(req)：将请求体解析为 表单数据 对象，返回 struct form_data * 指针。需要请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data。
⚝ form_data_get_value(form, name)：根据表单字段名 name 获取表单字段的值，返回字符串。
⚝ form_data_get_file(form, name)：根据表单字段名 name 获取上传的文件信息，返回 struct form_file * 指针 (仅适用于 multipart/form-data 请求)。
⚝ form_data_free(form)：释放 struct form_data * 对象。
② 表单验证：
表单验证是指对用户提交的表单数据进行有效性检查，确保数据符合预期的格式和规则。表单验证可以在客户端（JavaScript）和服务器端（C 语言）进行。服务器端验证更加可靠，是安全性的重要保障。
表单验证通常包括以下步骤：
1
1. **获取表单字段值**：使用 `form_data_get_value()` 函数获取表单字段的值。
2
2. **数据清洗和转换**：去除值的前后空格，将字符串转换为需要的类型（例如整数、浮点数、日期等）。
3
3. **验证规则检查**：根据业务规则，检查字段值是否符合要求，例如：
4
* 必填字段检查：检查字段值是否为空。
5
* 长度限制检查：检查字符串长度是否在指定范围内。
6
* 格式验证：使用 **正则表达式**（Regular Expression）或自定义函数验证字段格式，例如邮箱、手机号、URL 等。
7
* 取值范围检查：检查数值是否在指定范围内。
8
* 数据类型检查：检查数据类型是否符合要求。
9
4. **错误收集**：如果验证失败，记录错误信息，例如字段名、错误类型、错误提示等。
③ 表单处理与验证示例：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <form.h> // 引入 form.h
4
#include <string.h> // for strlen
5
#include <regex.h> // for regex validation
6
7
// 邮箱格式验证正则表达式 (简单示例，实际应用中可能需要更完善的正则)
8
#define EMAIL_REGEX "^[^@]+@[^@]+\\.[^@]+$"
9
10
int register_handler(struct http_request *);
11
int validate_email(const char *email); // 声明邮箱验证函数
12
13
int
14
register_handler(struct http_request *req)
15
{
16
struct form_data *form;
17
const char *username, *email, *password;
18
struct json_value *errors = json_object(); // 用于收集错误信息
19
int has_error = 0;
20
21
form = http_request_body_form(req); // 解析表单数据
22
if (form == NULL) {
23
http_response_error(req, 400); // Bad Request, 表单解析失败
24
return (KORE_RESULT_ERROR);
25
}
26
27
// 获取表单字段值
28
username = form_data_get_value(form, "username");
29
email = form_data_get_value(form, "email");
30
password = form_data_get_value(form, "password");
31
32
// 表单验证
33
if (username == NULL || strlen(username) < 3 || strlen(username) > 50) {
34
json_object_push(errors, "username", json_string("Username must be between 3 and 50 characters"));
35
has_error = 1;
36
}
37
38
if (email == NULL || !validate_email(email)) {
39
json_object_push(errors, "email", json_string("Invalid email format"));
40
has_error = 1;
41
}
42
43
if (password == NULL || strlen(password) < 6) {
44
json_object_push(errors, "password", json_string("Password must be at least 6 characters"));
45
has_error = 1;
46
}
47
48
if (has_error) {
49
// 验证失败，返回错误信息
50
http_response_status(req, 400); // Bad Request
51
http_response_header(req, "Content-Type", "application/json");
52
http_response_json(req, 400, errors);
53
json_value_free(errors);
54
form_data_free(form);
55
return (KORE_RESULT_OK);
56
}
57
58
// 验证成功，处理注册逻辑 (例如保存用户信息到数据库)
59
kore_log(LOG_INFO, "Registration successful for user: %s, email: %s", username, email);
60
http_response(req, 200, "Registration successful", 22);
61
62
json_value_free(errors); // 释放错误对象
63
form_data_free(form); // 释放表单数据对象
64
return (KORE_RESULT_OK);
65
}
66
67
// 邮箱格式验证函数 (使用正则表达式)
68
int
69
validate_email(const char *email)
70
{
71
regex_t regex;
72
int ret;
73
74
if (regcomp(®ex, EMAIL_REGEX, REG_EXTENDED | REG_NOSUB) != 0) {
75
kore_log(LOG_ERR, "regcomp failed for email regex");
76
return 0; // 正则编译失败，验证失败
77
}
78
79
ret = regexec(®ex, email, 0, NULL, 0);
80
regfree(®ex); // 释放正则表达式对象
81
82
if (ret == 0) {
83
return 1; // 匹配成功，邮箱格式有效
84
} else if (ret == REG_NOMATCH) {
85
return 0; // 不匹配，邮箱格式无效
86
} else {
87
kore_log(LOG_ERR, "regexec failed for email regex");
88
return 0; // 正则执行失败，验证失败
89
}
90
}
91
92
int
93
kore_main(int argc, char *argv[])
94
{
95
kore_http_handler_add("/register", register_handler);
96
return (KORE_RESULT_OK);
97
}
这个示例演示了如何获取表单数据、进行服务器端表单验证，并将验证错误信息以 JSON 格式返回给客户端。实际应用中，表单验证规则会更加复杂，可能需要根据具体业务需求进行扩展和完善。
6.4 身份验证与授权 (Authentication and Authorization) 🔑
身份验证（Authentication）和 授权（Authorization）是 Web 应用安全性的核心组成部分。身份验证 确认用户的身份，授权 决定用户是否有权限访问特定的资源或执行特定的操作。
Kore Web 框架没有内置完整的身份验证和授权系统，但可以基于 Kore 提供的 API 和 中间件 机制，实现各种身份验证和授权方案。
① 身份验证方案：
常见的身份验证方案包括：
⚝ 基于会话的身份验证（Session-based Authentication）：
用户登录成功后，服务器创建一个 会话，并将 会话 ID 存储在 Cookie 中返回给客户端。客户端后续请求携带 会话 Cookie，服务器根据 会话 Cookie 验证用户身份。Kore 的 会话管理 API ( http_session_create(), http_session_get(), http_session_set_string(), 等) 可以用于实现基于会话的身份验证。
⚝ 基于令牌的身份验证（Token-based Authentication）：
用户登录成功后，服务器生成一个 令牌（Token），例如 JSON Web Token (JWT)，并将令牌返回给客户端。客户端后续请求在 HTTP 头部 (例如 Authorization: Bearer <token>) 中携带令牌，服务器验证令牌的有效性。可以使用第三方 JWT 库 (例如 libjwt) 在 Kore 应用中生成和验证 JWT 令牌。
⚝ OAuth 2.0 身份验证：
OAuth 2.0 是一种授权框架，也可以用于身份验证。通过集成 OAuth 2.0 客户端库，Kore 应用可以作为 OAuth 2.0 客户端，与 OAuth 2.0 授权服务器 交互，实现第三方身份验证 (例如使用 Google, Facebook, GitHub 账号登录)。
② 授权方案：
常见的授权方案包括：
⚝ 基于角色的访问控制 (Role-Based Access Control, RBAC)：
为用户分配 角色（Role），例如管理员、普通用户、访客等。为每个 角色 定义一组 权限（Permission），例如读取文章、编辑文章、删除用户等。在进行授权检查时，判断用户所属的角色是否具有访问资源的权限。
⚝ 基于属性的访问控制 (Attribute-Based Access Control, ABAC)：
基于用户的属性、资源的属性、环境的属性等多个维度进行授权决策。ABAC 提供了更细粒度和更灵活的访问控制策略。
⚝ 访问控制列表 (Access Control List, ACL)：
为每个资源维护一个 访问控制列表，列表中列出允许访问该资源的用户或角色及其权限。
③ 身份验证与授权中间件示例 (基于会话和 RBAC)：
以下示例展示了如何使用 中间件 和 会话管理 API 实现基于会话的身份验证和基于角色的访问控制。
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <kore/session.h>
4
5
// 假设的用户角色定义
6
typedef enum {
7
ROLE_GUEST = 0,
8
ROLE_USER = 1,
9
ROLE_ADMIN = 2
10
} UserRole;
11
12
// 假设的用户信息结构
13
typedef struct {
14
int user_id;
15
char *username;
16
UserRole role;
17
} UserInfo;
18
19
// 假设的获取用户信息函数 (实际应用中需要从数据库或缓存中获取)
20
UserInfo *get_user_info(int user_id) {
21
if (user_id == 1) {
22
UserInfo *user = kore_malloc(sizeof(UserInfo));
23
user->user_id = 1;
24
user->username = kore_strdup("admin");
25
user->role = ROLE_ADMIN;
26
return user;
27
} else if (user_id == 2) {
28
UserInfo *user = kore_malloc(sizeof(UserInfo));
29
user->user_id = 2;
30
user->username = kore_strdup("user1");
31
user->role = ROLE_USER;
32
return user;
33
}
34
return NULL; // 用户不存在
35
}
36
37
// 身份验证中间件
38
int
39
auth_middleware(struct http_request *req, void *arg)
40
{
41
struct http_session *session = http_session_get(req);
42
if (session == NULL) {
43
http_response_redirect(req, 302, "/login"); // 未登录，重定向到登录页面
44
return (KORE_RESULT_ERROR);
45
}
46
47
const char *user_id_str = http_session_get_string(session, "user_id");
48
if (user_id_str == NULL) {
49
http_response_redirect(req, 302, "/login"); // 会话中 user_id 不存在，重定向到登录页面
50
return (KORE_RESULT_ERROR);
51
}
52
53
int user_id = atoi(user_id_str);
54
UserInfo *user_info = get_user_info(user_id); // 获取用户信息
55
if (user_info == NULL) {
56
http_response_redirect(req, 302, "/login"); // 用户信息获取失败，重定向到登录页面
57
return (KORE_RESULT_ERROR);
58
}
59
60
// 将用户信息存储在请求对象的用户数据中 (可选，方便后续处理器访问)
61
req->user_data = user_info;
62
63
return (KORE_RESULT_OK); // 身份验证通过，继续处理请求
64
}
65
66
// 授权中间件 (管理员权限检查)
67
int
68
admin_role_middleware(struct http_request *req, void *arg)
69
{
70
UserInfo *user_info = (UserInfo *)req->user_data; // 从请求对象中获取用户信息
71
if (user_info == NULL || user_info->role != ROLE_ADMIN) {
72
http_response_error(req, 403); // Forbidden, 无权限访问
73
return (KORE_RESULT_ERROR);
74
}
75
76
return (KORE_RESULT_OK); // 授权通过，继续处理请求
77
}
78
79
int
80
admin_dashboard_handler(struct http_request *req)
81
{
82
UserInfo *user_info = (UserInfo *)req->user_data; // 从请求对象中获取用户信息
83
http_response_header(req, "Content-Type", "text/plain");
84
http_response(req, 200, "Admin Dashboard, Welcome ", 25);
85
http_response_stream(req, user_info->username, strlen(user_info->username));
86
return (KORE_RESULT_OK);
87
}
88
89
int
90
login_handler(struct http_request *req)
91
{
92
// ... 处理登录逻辑，验证用户名密码
93
if (/* 登录验证成功 */ 1) {
94
struct http_session *session = http_session_create(req);
95
http_session_set_string(session, "user_id", "1"); // 假设用户 ID 为 1
96
http_response_redirect(req, 302, "/admin/dashboard"); // 登录成功，重定向到管理后台
97
return (KORE_RESULT_OK);
98
} else {
99
http_response_error(req, 401); // Unauthorized, 登录失败
100
return (KORE_RESULT_ERROR);
101
}
102
}
103
104
int
105
kore_main(int argc, char *argv[])
106
{
107
kore_http_handler_add("/login", login_handler);
108
kore_http_handler_add_middleware("/admin/dashboard", auth_middleware, admin_dashboard_handler); // 需要身份验证
109
kore_http_handler_add_middleware("/admin/dashboard", admin_role_middleware, admin_dashboard_handler); // 需要管理员权限
110
return (KORE_RESULT_OK);
111
}
这个示例演示了如何使用 中间件 实现身份验证和授权，保护需要授权才能访问的资源。实际应用中，身份验证和授权逻辑会更加复杂，需要根据具体的安全需求进行设计和实现。
Chapter 6 深入探讨了 Kore Web 应用开发的实践技巧和最佳实践，包括项目结构与组织、模板引擎集成、表单处理与验证、身份验证与授权。掌握这些内容可以帮助开发者构建高质量、可维护、安全的 Kore Web 应用。在接下来的章节中，我们将学习 Kore 应用的安全性、测试与部署等高级主题。
7. chapter 7： Kore 安全性 🛡️
7.1 常见 Web 安全漏洞 ⚠️
Web 应用安全至关重要。理解常见的 Web 安全漏洞（Web Security Vulnerabilities）是构建安全 Kore Web 应用的第一步。以下列举了一些常见的 Web 安全漏洞：
① 跨站脚本攻击 (XSS)（Cross-Site Scripting, XSS）：
XSS 攻击是指攻击者将恶意 JavaScript 代码注入到 Web 页面中，当用户浏览被注入恶意代码的页面时，恶意脚本会在用户的浏览器中执行，从而窃取用户的 Cookie、会话 信息，或者进行恶意操作。
⚝ 类型：
▮▮▮▮ⓐ 反射型 XSS（Reflected XSS）：恶意脚本通过 URL 参数或其他用户请求输入的方式注入，服务器端没有进行充分的过滤和转义，直接在响应中输出了恶意脚本，导致脚本在用户浏览器端执行。
▮▮▮▮ⓑ 存储型 XSS（Stored XSS）：恶意脚本被存储在服务器端的数据库或其他持久化存储中，当用户请求包含恶意脚本的数据时，服务器端将恶意脚本从存储中取出并输出到页面，从而导致脚本在用户浏览器端执行。
▮▮▮▮ⓒ DOM-based XSS（DOM-based XSS）：恶意脚本不经过服务器端，而是通过修改页面的 DOM (Document Object Model) 结构来注入，例如利用客户端 JavaScript 代码中的漏洞。
⚝ 防范措施：
▮▮▮▮ⓐ 输入验证（Input Validation）：对所有用户输入进行严格的验证，拒绝不合法的输入。
▮▮▮▮ⓑ 输出编码（Output Encoding）：在将用户输入输出到 HTML 页面时，进行合适的编码和转义，例如 HTML 实体编码，防止恶意脚本被浏览器解析执行。
▮▮▮▮ⓒ 内容安全策略 (CSP)（Content Security Policy, CSP）：配置 CSP 头部，限制浏览器加载和执行外部资源的来源，降低 XSS 攻击的风险。
▮▮▮▮ⓓ HttpOnly Cookie：对于存储 会话 ID 等敏感信息的 Cookie，设置 HttpOnly 标志，防止客户端 JavaScript 访问 Cookie。
② SQL 注入 (SQL Injection)：
SQL 注入 攻击是指攻击者通过在 Web 应用的输入字段中注入恶意的 SQL 代码，欺骗数据库服务器执行非预期的 SQL 查询，从而窃取、修改或删除数据库中的数据，甚至控制数据库服务器。
⚝ 类型：
▮▮▮▮ⓐ 基于错误的 SQL 注入（Error-based SQL Injection）：通过构造恶意的 SQL 查询，使数据库服务器返回错误信息，从而推断数据库结构和数据。
▮▮▮▮ⓑ 盲注（Blind SQL Injection）：在数据库服务器不返回错误信息的情况下，通过构造不同的 SQL 查询，根据页面响应的差异（例如响应时间、内容差异）来推断数据库信息。
▮▮▮▮ⓒ 时间盲注（Time-based Blind SQL Injection）：通过在 SQL 查询中引入延时函数，根据页面响应时间的长短来判断 SQL 注入是否成功。
⚝ 防范措施：
▮▮▮▮ⓐ 使用参数化查询（Parameterized Query）或 预编译语句（Prepared Statement）：使用 参数化查询 或 预编译语句 可以有效地防止 SQL 注入 攻击，将 SQL 语句和用户输入数据分离，避免用户输入的数据被解析为 SQL 代码执行。
▮▮▮▮ⓑ 最小权限原则（Principle of Least Privilege）：数据库连接用户只授予必要的权限，避免授予过高的权限，降低 SQL 注入 攻击的危害。
▮▮▮▮ⓒ 输入验证：对用户输入进行严格的验证，过滤掉可能包含恶意 SQL 代码的输入。
▮▮▮▮ⓓ Web 应用防火墙 (WAF)（Web Application Firewall, WAF）：使用 WAF 检测和防御 SQL 注入 攻击。
③ 跨站请求伪造 (CSRF)（Cross-Site Request Forgery, CSRF）：
CSRF 攻击是指攻击者伪造用户的请求，以用户的身份执行非预期的操作，例如修改用户密码、转账等。CSRF 攻击通常发生在用户已经登录的情况下。
⚝ 防范措施：
▮▮▮▮ⓐ 同步令牌 (CSRF Token)（Synchronizer Token Pattern）：在服务器端生成一个随机的 CSRF Token，在页面表单中包含该 Token，并在服务器端验证请求中的 CSRF Token 是否与服务器端生成的 Token 一致。
▮▮▮▮ⓑ SameSite Cookie：设置 Cookie 的 SameSite 属性为 Strict 或 Lax，限制 Cookie 在跨站请求中的发送，降低 CSRF 攻击的风险。
▮▮▮▮ⓒ 验证 HTTP Referer 头部：检查 HTTP Referer 头部，验证请求来源是否合法。但 Referer 头部可能被伪造或浏览器禁用，可靠性较低。
④ 不安全的反序列化（Insecure Deserialization）：
反序列化 是将序列化的数据转换回原始对象的过程。不安全的反序列化 漏洞是指当应用程序反序列化来自不可信来源的数据时，可能导致代码执行、拒绝服务攻击等安全问题。
⚝ 防范措施：
▮▮▮▮ⓐ 避免反序列化不可信数据：尽量避免反序列化来自不可信来源的数据。
▮▮▮▮ⓑ 使用安全的序列化/反序列化机制：选择安全的序列化/反序列化库和格式，例如 JSON，避免使用存在安全风险的序列化机制，例如 PHP 的 unserialize() 函数、 Python 的 pickle 模块。
▮▮▮▮ⓒ 输入验证：对反序列化之前的数据进行严格的验证，确保数据的合法性。
⑤ 认证和会话管理漏洞（Authentication and Session Management Vulnerabilities）：
认证和会话管理是 Web 应用安全的基础，如果认证和会话管理机制存在漏洞，可能导致身份冒用、会话劫持等安全问题。
⚝ 类型：
▮▮▮▮ⓐ 弱密码（Weak Password）：用户使用弱密码，容易被暴力破解。
▮▮▮▮ⓑ 会话固定（Session Fixation）：攻击者诱导用户使用攻击者已知的 会话 ID 登录，然后攻击者可以使用该 会话 ID 冒充用户。
▮▮▮▮ⓒ 会话劫持（Session Hijacking）：攻击者通过某种方式窃取用户的 会话 ID，然后使用该 会话 ID 冒充用户。
▮▮▮▮ⓓ 会话超时时间过长（Excessive Session Timeout）：会话超时时间设置过长，用户长时间不操作后，会话仍然有效，增加会话泄露的风险。
⚝ 防范措施：
▮▮▮▮ⓐ 强制使用强密码：要求用户设置符合安全强度的密码，例如包含大小写字母、数字、特殊字符，并限制密码长度。
▮▮▮▮ⓑ 密码加密存储：使用安全的哈希算法（例如 bcrypt, Argon2）对用户密码进行加密存储，避免明文存储密码。
▮▮▮▮ⓒ 防止会话固定：在用户登录成功后，重新生成新的 会话 ID，使旧的 会话 ID 失效。
▮▮▮▮ⓓ 使用安全 Cookie 属性：为 会话 Cookie 设置 HttpOnly 和 Secure 标志，防止客户端 JavaScript 访问 Cookie，并只在 HTTPS 连接中发送 Cookie。
▮▮▮▮ⓔ 设置合理的会话超时时间：根据应用场景设置合理的会话超时时间，并提供 会话超时自动注销 功能。
▮▮▮▮ⓕ 多因素身份验证 (MFA)（Multi-Factor Authentication, MFA）：启用 MFA，增加身份验证的安全性，例如结合密码和短信验证码、 TOTP (Time-based One-time Password) 等。
⑥ 点击劫持 (Clickjacking)（Clickjacking）：
点击劫持 攻击是指攻击者将恶意链接或按钮覆盖在正常网页的透明或半透明的 iframe 上，诱导用户点击，从而在用户不知情的情况下执行恶意操作。
⚝ 防范措施：
▮▮▮▮ⓐ X-Frame-Options 头部：配置 X-Frame-Options 头部，限制网页被嵌入到 iframe 中的行为。常用的值包括 DENY (禁止所有域名嵌入) 和 SAMEORIGIN (只允许同源域名嵌入)。
▮▮▮▮ⓑ Content-Security-Policy (CSP) frame-ancestors 指令：使用 CSP 的 frame-ancestors 指令，更灵活地控制网页可以被嵌入的来源。
▮▮▮▮ⓒ 客户端防御 JavaScript 代码：使用客户端 JavaScript 代码检测页面是否被嵌入到 iframe 中，如果是则阻止页面操作。但客户端防御可能被绕过。
⑦ 拒绝服务攻击 (DoS) 和 分布式拒绝服务攻击 (DDoS)（Denial of Service, DoS & Distributed Denial of Service, DDoS）：
DoS 和 DDoS 攻击是指攻击者通过发送大量的恶意请求，消耗服务器资源，导致服务器无法正常响应用户的请求，从而达到拒绝服务的目的。DDoS 攻击是 DoS 攻击的分布式形式，攻击流量来自多个攻击源，更难防御。
⚝ 类型：
▮▮▮▮ⓐ SYN Flood 攻击：攻击者发送大量的 SYN 包，但不完成 TCP 三次握手，消耗服务器的连接资源。
▮▮▮▮ⓑ HTTP Flood 攻击：攻击者发送大量的 HTTP 请求，消耗服务器的计算和带宽资源。
▮▮▮▮ⓒ 慢速 HTTP 攻击（Slow HTTP Attack）：攻击者以极低的速度发送 HTTP 请求 或 HTTP 请求头，长时间占用服务器连接资源。
⚝ 防范措施：
▮▮▮▮ⓐ 限制请求频率（Rate Limiting）：限制客户端 IP 地址或用户的请求频率，防止恶意请求占用过多资源。
▮▮▮▮ⓑ Web 应用防火墙 (WAF)（Web Application Firewall, WAF）：使用 WAF 检测和防御 DoS/DDoS 攻击。
▮▮▮▮ⓒ 负载均衡（Load Balancing）：使用 负载均衡 将请求分发到多台服务器，提高系统的整体抗 DDoS 能力。
▮▮▮▮ⓓ 内容分发网络 (CDN)（Content Delivery Network, CDN）：使用 CDN 缓存静态资源，并将请求分发到全球各地的节点，分散攻击流量。
▮▮▮▮ⓔ 使用 DDoS 防护服务：使用专业的 DDoS 防护服务，例如云服务提供商提供的 DDoS 高防 IP 服务。
7.2 Kore 的安全特性 💯
Kore Web 框架在设计和实现上注重安全性，提供了一些安全特性，帮助开发者构建更安全的 Web 应用。
① C 语言的安全性：
Kore 使用 C 语言 开发，C 语言 是一种编译型语言，相对于解释型语言，在性能和安全性方面具有一定的优势。C 语言 代码直接编译成机器码执行，避免了解释器带来的额外开销和潜在的安全风险。同时，C 语言 提供了更底层的控制能力，开发者可以更精细地管理内存和系统资源，提高程序的安全性和可靠性。
② 代码库精简：
Kore 的代码库相对精简，核心功能与扩展功能分离，这降低了代码审查的难度，并减少了潜在的安全漏洞。精简的代码库也意味着更小的攻击面，降低了被攻击者利用的风险。
③ 内存安全：
Kore 开发团队在框架设计和实现上非常注重 内存安全，努力避免常见的 C 语言 内存错误，例如缓冲区溢出、内存泄漏、野指针等。Kore 鼓励开发者遵循安全的编程实践，例如使用安全的字符串处理函数、进行边界检查、避免内存越界访问等。
④ HTTPS 支持：
Kore 内置支持 HTTPS 协议，可以通过配置 kore.conf 文件中的 tls 块启用 HTTPS。HTTPS 使用 TLS/SSL 协议对 HTTP 通信进行加密，保护数据在传输过程中的安全性和完整性，防止数据被窃听和篡改。
⑤ 会话管理安全：
Kore 提供的 会话管理 API 默认启用了以下安全特性：
* HttpOnly Cookie：默认情况下，会话 Cookie 设置了 HttpOnly 标志，防止客户端 JavaScript 访问 会话 Cookie，降低 XSS 攻击导致 会话 ID 泄露的风险。
* Secure Cookie：默认情况下，会话 Cookie 设置了 Secure 标志，只在 HTTPS 连接中发送 会话 Cookie，防止 会话 ID 在 HTTP 连接中被窃听。
* 会话 ID 安全生成：Kore 使用安全的随机数生成器生成 会话 ID，增加 会话 ID 的随机性和不可预测性，降低被暴力破解或猜测的风险。
⑥ 主机头保护（Host Header Protection）：
Kore 可以配置 allowed_hosts 配置项，限制允许访问的主机名列表，防止 主机头攻击（Host Header Attack）。主机头攻击 是指攻击者通过修改 HTTP Host 头部，欺骗 Web 应用处理非预期的主机请求，可能导致安全漏洞。
⑦ 请求体大小限制：
Kore 允许通过 kore.conf 文件中的 server.http.max_request_body 配置项设置最大请求体大小限制，防止上传过大的文件或恶意请求消耗过多服务器资源，降低 DoS 攻击的风险。
⑧ 安全编码实践：
Kore 框架本身的代码编写遵循安全编码实践，例如代码审查、单元测试、模糊测试等，努力减少框架自身存在的安全漏洞。
7.3 安全开发最佳实践 🧑💻
除了 Kore 框架提供的安全特性外，开发者在 Kore Web 应用开发过程中，也需要遵循一些安全开发最佳实践，从代码层面提高应用的安全性。
① 输入验证与输出编码：
对所有用户输入进行严格的验证，包括请求参数、请求头、请求体等，拒绝不合法的输入。在将用户输入输出到 HTML 页面、 SQL 查询、日志等场景时，进行合适的编码和转义，防止 XSS、 SQL 注入 等漏洞。
② 使用参数化查询或预编译语句：
在进行数据库操作时，务必使用 参数化查询 或 预编译语句，避免拼接 SQL 语句，防止 SQL 注入 攻击。
③ 实施 CSRF 防护：
在重要的表单提交操作中，实施 CSRF 防护，例如使用 同步令牌 (CSRF Token) 或设置 SameSite Cookie，防止 CSRF 攻击。
④ 安全处理敏感数据：
对于用户密码、身份
证号码、银行卡号等敏感数据，进行加密存储和传输，避免明文泄露。在日志中避免记录敏感数据。
⑤ 最小权限原则：
在配置数据库连接、文件系统权限、操作系统权限等时，遵循 最小权限原则，只授予必要的权限，避免授予过高的权限，降低安全风险。
⑥ 定期安全审计和漏洞扫描：
定期对 Kore Web 应用进行安全审计和漏洞扫描，及时发现和修复潜在的安全漏洞。可以使用专业的安全扫描工具，例如 OWASP ZAP、 Nessus 等。
⑦ 关注安全更新：
关注 Kore Web 框架和所使用的第三方库的安全更新，及时升级到最新版本，修复已知的安全漏洞。
⑧ 安全意识培训：
加强开发团队的安全意识培训，提高开发人员的安全编码能力，从源头上减少安全漏洞的产生。
⑨ 配置安全 HTTP 头部：
根据应用需求，配置安全 HTTP 头部，例如：
* Content-Security-Policy：配置 CSP，限制资源加载来源，防止 XSS 攻击。
* X-Frame-Options：配置 X-Frame-Options，防止 点击劫持 攻击。
* X-Content-Type-Options: nosniff：阻止浏览器 MIME 类型嗅探，防止某些类型的 XSS 攻击。
* Strict-Transport-Security：配置 HSTS，强制浏览器使用 HTTPS 连接。
* Referrer-Policy：配置 Referrer-Policy，控制 Referer 头部信息的发送，保护用户隐私。
⑩ 安全部署配置：
在部署 Kore Web 应用时，进行安全配置，例如：
* 禁用不必要的服务和端口：只开放必要的端口，例如 HTTP/HTTPS 端口，关闭不必要的服务和端口，减少攻击面。
* 使用防火墙：配置防火墙，限制对服务器的访问，只允许来自合法来源的请求。
* 定期更新操作系统和软件：保持操作系统和服务器软件的更新，修复已知的安全漏洞。
* 监控和日志：配置完善的监控和日志系统，及时发现和响应安全事件。
通过理解常见的 Web 安全漏洞，利用 Kore 提供的安全特性，并遵循安全开发最佳实践，可以有效地提高 Kore Web 应用的安全性，保护用户数据和系统安全。
Chapter 7 深入探讨了 Kore Web 框架的安全性，包括常见的 Web 安全漏洞、Kore 的安全特性以及安全开发最佳实践。掌握这些内容对于构建安全可靠的 Kore Web 应用至关重要。在接下来的章节中，我们将继续学习 Kore 应用的测试与部署以及高级主题。
8. chapter 8： Kore 测试与部署 ✅🚀
8.1 单元测试 (Unit Testing) 🧪
单元测试（Unit Testing）是软件测试的基础环节，旨在验证代码的最小可测试单元（通常是函数或模块）的功能是否符合预期。在 Kore Web 框架开发中，编写高质量的单元测试对于保证代码质量、尽早发现和修复 Bug、以及支持 持续集成（Continuous Integration, CI）至关重要。
① 单元测试框架：
对于 C 语言 项目，有多种单元测试框架可供选择，例如：
⚝ Check：https://libcheck.github.io/check/
Check 是一个流行的 C 语言 单元测试框架，提供了简洁的 API 和丰富的断言宏，易于使用和集成。
⚝ cmocka：https://cmocka.org/
cmocka 是另一个轻量级的 C 语言 单元测试框架，支持 Mock 对象（Mock Object），方便测试依赖外部模块的代码单元。
⚝ Unity：https://github.com/ThrowTheSwitch/Unity
Unity 是一个简单但功能强大的 C 语言 单元测试框架，常用于 嵌入式系统（Embedded System）开发，也适用于一般的 C 语言 项目。
② 单元测试编写原则：
编写有效的单元测试需要遵循一些原则：
⚝ 测试独立性：单元测试应该相互独立，不依赖于其他测试用例的执行结果。每个测试用例应该能够独立运行，并验证一个特定的功能点。
⚝ 测试覆盖率：单元测试应该尽可能覆盖被测代码的各种情况，包括正常情况、边界情况、异常情况等。可以使用代码覆盖率工具（例如 gcov, lcov）来衡量测试覆盖率。
⚝ 快速执行：单元测试应该能够快速执行，以便频繁运行，及时发现问题。避免在单元测试中进行耗时的操作，例如数据库访问、网络请求等。
⚝ 可重复执行：单元测试的结果应该是可重复的，相同的输入应该得到相同的输出。避免在单元测试中使用随机数或依赖外部环境的状态。
⚝ 易于维护：单元测试代码也需要易于维护，命名清晰，结构合理，避免过度复杂的测试逻辑。
③ Kore 单元测试示例 (使用 Check 框架)：
假设我们有一个简单的工具函数 utils/string_utils.c，其中包含一个函数 string_reverse() 用于反转字符串。
1
// src/utils/string_utils.c
2
#include <string.h>
3
#include <stdlib.h>
4
5
char *
6
string_reverse(const char *str)
7
{
8
if (str == NULL) {
9
return NULL;
10
}
11
size_t len = strlen(str);
12
char *reversed_str = malloc(len + 1);
13
if (reversed_str == NULL) {
14
return NULL; // 内存分配失败
15
}
16
for (size_t i = 0; i < len; i++) {
17
reversed_str[i] = str[len - 1 - i];
18
}
19
reversed_str[len] = '\0';
20
return reversed_str;
21
}
现在我们使用 Check 框架为 string_reverse() 函数编写单元测试。
- 创建测试文件
test/string_utils_test.c：
1
#include <check.h>
2
#include <stdlib.h>
3
#include "utils/string_utils.h" // 假设 utils 目录在 include 路径下
4
5
START_TEST(test_string_reverse_basic)
6
{
7
char *reversed = string_reverse("hello");
8
ck_assert_str_eq(reversed, "olleh");
9
free(reversed);
10
}
11
END_TEST
12
13
START_TEST(test_string_reverse_empty)
14
{
15
char *reversed = string_reverse("");
16
ck_assert_str_eq(reversed, "");
17
free(reversed);
18
}
19
END_TEST
20
21
START_TEST(test_string_reverse_null)
22
{
23
char *reversed = string_reverse(NULL);
24
ck_assert_ptr_null(reversed);
25
}
26
END_TEST
27
28
START_TEST(test_string_reverse_palindrome)
29
{
30
char *reversed = string_reverse("madam");
31
ck_assert_str_eq(reversed, "madam");
32
free(reversed);
33
}
34
END_TEST
35
36
Suite *
37
string_utils_suite(void)
38
{
39
Suite *s;
40
TCase *tc_core;
41
42
s = suite_create("String Utils");
43
44
tc_core = tcase_create("Core");
45
46
tcase_add_test(tc_core, test_string_reverse_basic);
47
tcase_add_test(tc_core, test_string_reverse_empty);
48
tcase_add_test(tc_core, test_string_reverse_null);
49
tcase_add_test(tc_core, test_string_reverse_palindrome);
50
51
suite_add_tcase(s, tc_core);
52
53
return s;
54
}
55
56
int
57
main(void)
58
{
59
int number_failed;
60
Suite *s = string_utils_suite();
61
SRunner *sr = srunner_create(s);
62
63
srunner_run_all(sr, CK_NORMAL);
64
number_failed = srunner_ntests_failed(sr);
65
srunner_free(sr);
66
return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE;
67
}
- 修改
Makefile添加测试编译和运行：
在 Makefile 中添加编译和运行单元测试的规则。
1
# ... (原有 Makefile 内容)
2
3
TEST_PROG = string_utils_test
4
TEST_SRCS = test/string_utils_test.c src/utils/string_utils.c # 包含测试文件和被测试文件
5
TEST_OBJS = $(TEST_SRCS:.c=.o)
6
TEST_CFLAGS = $(CFLAGS) -I/usr/local/include # Check 头文件路径
7
TEST_LIBS = $(LIBS) -lcheck # Check 库
8
9
$(TEST_PROG): $(TEST_OBJS)
10
$(CC) $(TEST_CFLAGS) -o $(TEST_PROG) $(TEST_OBJS) $(TEST_LIBS)
11
12
test: $(TEST_PROG)
13
./$(TEST_PROG)
14
15
# ... (原有 Makefile 内容)
16
17
.PHONY: install clean test
- 编译和运行单元测试：
执行 make test 命令编译和运行单元测试。如果所有测试用例都通过，则表示 string_reverse() 函数的功能基本正确。
1
make test
2
./string_utils_test
3
Running suite(s): String Utils
4
100%: Checks: 4, Failures: 0, Errors: 0
8.2 集成测试 (Integration Testing) 🔗
集成测试（Integration Testing）是在单元测试的基础上，将多个已测试的单元模块组合起来进行测试，验证模块之间的接口和交互是否正确。在 Kore Web 应用中，集成测试可以验证 处理器（Handler）、 中间件（Middleware）、 数据模型（Data Model）、 数据库 等组件之间的协同工作是否符合预期。
① 集成测试策略：
⚝ 自顶向下集成（Top-Down Integration）：从顶层模块开始，逐步集成下层模块。适用于系统架构清晰、顶层模块稳定的情况。
⚝ 自底向上集成（Bottom-Up Integration）：从底层模块开始，逐步集成上层模块。适用于底层模块稳定、接口定义清晰的情况。
⚝ 大爆炸集成（Big-Bang Integration）：一次性将所有模块集成起来进行测试。适用于小型系统或快速验证整体功能的情况，但问题定位和调试难度较大。
② 集成测试关注点：
⚝ 模块接口：验证模块之间的接口定义是否一致，数据传递是否正确。
⚝ 数据流：验证数据在模块之间的流动是否符合预期，数据处理是否正确。
⚝ 外部依赖：验证应用与外部依赖（例如数据库、外部 API）的集成是否正常。
⚝ 错误处理：验证模块之间的错误传递和处理机制是否正确。
⚝ 性能：初步评估集成后的系统性能，例如响应时间、吞吐量等。
③ Kore 集成测试示例 (模拟 HTTP 请求)：
对于 Kore Web 应用的集成测试，可以模拟 HTTP 请求，发送到运行中的 Kore 应用，然后验证响应结果。可以使用 C 语言 的 HTTP 客户端库（例如 libcurl）或更简单的工具来发送 HTTP 请求。
以下示例演示如何使用 libcurl 模拟 HTTP GET 请求，测试一个简单的 Kore 处理器。
- 假设有一个简单的 Kore 处理器
hello_handler()：
1
// src/handlers/hello.c
2
#include <kore.h>
3
#include <kore/http.h>
4
5
int
6
hello_handler(struct http_request *req)
7
{
8
http_response_header(req, "Content-Type", "text/plain");
9
http_response(req, 200, "Hello, Integration Test!", 25);
10
return (KORE_RESULT_OK);
11
}
12
13
// ... (kore_main 中注册了 /hello 路由)
- 创建集成测试文件
test/integration_test.c(使用 libcurl)：
1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <string.h>
4
#include <curl/curl.h> // 引入 libcurl
5
6
#define TEST_URL "http://localhost:8888/hello" // 测试 URL
7
8
struct MemoryStruct {
9
char *memory;
10
size_t size;
11
};
12
13
static size_t
14
WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
15
{
16
size_t realsize = size * nmemb;
17
struct MemoryStruct *mem = (struct MemoryStruct *)userp;
18
19
char *ptr = realloc(mem->memory, mem->size + realsize + 1);
20
if(ptr == NULL) {
21
printf("not enough memory (realloc returned NULL)\n");
22
return 0;
23
}
24
25
mem->memory = ptr;
26
memcpy(&(mem->memory[mem->size]), contents, realsize);
27
mem->size += realsize;
28
mem->memory[mem->size] = 0;
29
30
return realsize;
31
}
32
33
int
34
main(void)
35
{
36
CURL *curl;
37
CURLcode res;
38
struct MemoryStruct chunk;
39
40
chunk.memory = malloc(1); /* 初始分配一块小内存 */
41
chunk.size = 0; /* 实际数据大小为 0 */
42
43
curl_global_init(CURL_GLOBAL_ALL);
44
curl = curl_easy_init();
45
if(curl) {
46
curl_easy_setopt(curl, CURLOPT_URL, TEST_URL);
47
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
48
curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
49
curl_easy_setopt(curl, CURLOPT_USERAGENT, "Kore-Integration-Test-Agent/1.0");
50
51
res = curl_easy_perform(curl); // 执行 HTTP 请求
52
53
if(res != CURLE_OK) {
54
fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
55
goto cleanup;
56
} else {
57
long response_code;
58
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code); // 获取 HTTP 状态码
59
printf("Response code: %ld\n", response_code);
60
printf("Response body:\n%s\n", chunk.memory);
61
62
if (response_code != 200) {
63
fprintf(stderr, "Integration test failed: HTTP status code is not 200\n");
64
goto cleanup;
65
}
66
if (strstr(chunk.memory, "Hello, Integration Test!") == NULL) {
67
fprintf(stderr, "Integration test failed: Response body does not contain expected message\n");
68
goto cleanup;
69
}
70
71
printf("Integration test passed!\n");
72
}
73
74
cleanup:
75
curl_easy_cleanup(curl);
76
}
77
free(chunk.memory);
78
curl_global_cleanup();
79
return 0;
80
}
- 修改
Makefile添加集成测试编译和运行：
1
# ... (原有 Makefile 内容)
2
3
INTEGRATION_TEST_PROG = integration_test
4
INTEGRATION_TEST_SRCS = test/integration_test.c
5
INTEGRATION_TEST_OBJS = $(INTEGRATION_TEST_SRCS:.c=.o)
6
INTEGRATION_TEST_CFLAGS = $(CFLAGS) -I/usr/local/include # libcurl 头文件路径
7
INTEGRATION_TEST_LIBS = $(LIBS) -lcurl # libcurl 库
8
9
$(INTEGRATION_TEST_PROG): $(INTEGRATION_TEST_OBJS)
10
$(CC) $(INTEGRATION_TEST_CFLAGS) -o $(INTEGRATION_TEST_PROG) $(INTEGRATION_TEST_OBJS) $(INTEGRATION_TEST_LIBS)
11
12
integration-test: $(INTEGRATION_TEST_PROG) $(PROG)
13
@echo "Starting Kore application for integration test..."
14
@./$(PROG) & # 后台启动 Kore 应用
15
@sleep 1 # 等待 Kore 应用启动
16
@echo "Running integration test..."
17
@./$(INTEGRATION_TEST_PROG)
18
@pkill $(PROG) # 结束 Kore 应用进程
19
20
# ... (原有 Makefile 内容)
21
22
.PHONY: install clean test integration-test
- 编译和运行集成测试：
执行 make integration-test 命令编译并运行集成测试。集成测试会先启动 Kore 应用，然后发送 HTTP 请求 到 /hello 路径，验证响应状态码和响应体内容。
1
make integration-test
2
Starting Kore application for integration test...
3
Running integration test...
4
Response code: 200
5
Response body:
6
Hello, Integration Test!
7
8
Integration test passed!
9
pkill my-kore-app
8.3 性能测试 (Performance Testing) 📊
性能测试（Performance Testing）用于评估 Kore Web 应用在不同负载条件下的性能表现，例如响应时间、吞吐量、并发用户数、资源消耗等。性能测试是保证应用在高负载环境下稳定可靠运行的重要手段。
① 性能测试类型：
⚝ 负载测试（Load Testing）：模拟实际用户负载，逐步增加并发用户数或请求频率，测试系统在正常负载下的性能表现。
⚝ 压力测试（Stress Testing）：超过系统正常负载能力，持续增加负载，测试系统在极限负载下的稳定性和 容错能力（Fault Tolerance）。
⚝ 容量测试（Capacity Testing）：测试系统在不同硬件配置下的最大容量，例如最大并发用户数、最大吞吐量等。
⚝ 基准测试（Benchmarking）：与已知的性能基准进行对比，评估系统的性能水平。
② 性能测试工具：
⚝ Apache Benchmark (ab)：https://httpd.apache.org/docs/current/programs/ab.html
ab 是 Apache HTTP 服务器自带的性能测试工具，简单易用，适用于 HTTP 负载测试和基准测试。
⚝ wrk：https://github.com/wg/wrk
wrk 是一个现代 HTTP 基准测试工具，基于多线程和事件驱动，性能高效，可以模拟高并发负载。
⚝ Vegeta：https://github.com/tsenart/vegeta
Vegeta 是一个用 Go 语言编写的 HTTP 负载测试工具，支持多种负载模式和指标监控。
⚝ JMeter：https://jmeter.apache.org/
JMeter 是 Apache 基金会开发的 Java 应用，功能强大的性能测试工具，支持多种协议（包括 HTTP, WebSocket, 数据库 等），提供丰富的测试功能和报告。
③ Kore 性能测试示例 (使用 wrk 工具)：
以下示例演示如何使用 wrk 工具对 Kore Web 应用进行简单的性能测试。
(1). 安装 wrk 工具：
根据 wrk 的官方文档，下载源代码并编译安装。
1
git clone https://github.com/wg/wrk.git
2
cd wrk
3
make
4
sudo cp wrk /usr/local/bin/
(2). 运行 wrk 性能测试：
假设 Kore Web 应用运行在 http://localhost:8888，使用 wrk 工具进行 负载测试，模拟 12 个线程，100 个并发连接，持续 30 秒。
1
wrk -t12 -c100 -d30s http://localhost:8888/hello
wrk 会输出性能测试结果，包括请求总数、平均响应时间、每秒请求数 (Requests/sec)、吞吐量 (Transfer/sec) 等指标。
1
Running 30s test @ http://localhost:8888/hello
2
12 threads and 100 connections
3
Thread Stats Avg Stdev Max +/- Stdev
4
Latency 4.31ms 1.80ms 24.09ms 87.81%
5
Req/Sec 1.92k 396.65 2.60k 75.00%
6
574543 requests in 30.00s, 74.69MB read
7
Requests/sec: 19151.41
8
Transfer/sec: 2.49MB
根据性能测试结果，可以评估 Kore Web 应用的性能表现，并进行性能优化。
④ 性能优化策略：
针对性能测试发现的瓶颈，可以采取以下性能优化策略：
⚝ 代码优化：优化代码逻辑，减少不必要的计算和内存分配，提高代码执行效率。
⚝ 数据库优化：优化数据库查询语句，添加索引，使用连接池，提高数据库访问性能。
⚝ 缓存：使用 缓存（例如内存缓存、Redis, Memcached）缓存 frequently accessed data，减少对数据库的访问次数。
⚝ 压缩：启用 HTTP 压缩（例如 gzip, Brotli）压缩响应内容，减少网络传输量。
⚝ 连接复用（Keep-Alive）：启用 HTTP Keep-Alive，复用 TCP 连接，减少连接建立和关闭的开销。
⚝ 负载均衡：使用 负载均衡 将请求分发到多台服务器，提高系统的整体处理能力。
⚝ 反向代理（Reverse Proxy）：使用 反向代理 服务器（例如 Nginx, HAProxy）处理静态资源请求，并作为负载均衡器和缓存服务器。
⚝ 调整 Kore 配置：根据硬件资源和负载情况，调整 Kore 的配置参数，例如工作进程数、监听队列长度、最大连接数等。
8.4 部署到生产环境 (Deployment to Production) ☁️
部署到生产环境（Deployment to Production）是将开发完成、测试通过的 Kore Web 应用发布到生产服务器，对外提供服务的最后一步。一个稳定可靠的部署流程对于保证应用的可用性和稳定性至关重要。
① 服务器环境准备：
⚝ 选择合适的操作系统：推荐使用 Linux 发行版（例如 Ubuntu, CentOS, Debian）作为生产服务器操作系统。
⚝ 安装必要的软件：安装 C 编译器（例如 gcc, clang）、 make、 openssl、 pcre、 zlib 等 Kore 依赖的库。
⚝ 配置防火墙：配置防火墙（例如 iptables, firewalld, ufw），只允许必要的端口（例如 80, 443）对外开放，限制不必要的端口访问。
⚝ 安全加固：进行服务器安全加固，例如禁用不必要的服务、更新系统补丁、配置 SSH 安全、限制 root 用户远程登录等。
② Kore 应用编译和安装：
在生产服务器上，从源代码编译和安装 Kore Web 应用。
1
# 克隆代码仓库 (如果不是直接在服务器上开发)
2
git clone <your-repository-url>
3
cd <your-project-directory>
4
5
# 编译应用
6
make
7
8
# 安装应用 (将可执行文件复制到 /usr/local/bin 或其他目录)
9
sudo make install
③ 配置 Kore 应用：
⚝ 配置文件 kore.conf：根据生产环境需求，配置 kore.conf 文件，例如：
* server "http" { listen = "0.0.0.0:80"; processes = <cpu-cores>; }：配置监听地址和端口、工作进程数。
* accesslog "/var/log/kore/access.log"，errorlog "/var/log/kore/error.log"：配置访问日志和错误日志路径。
* tls { certificate = "/etc/kore/tls/server.crt"; key = "/etc/kore/tls/server.key"; }：配置 HTTPS 证书和私钥路径。
* database "mydb" { ... }：配置数据库连接信息。
* session { ... }：配置会话管理。
* allowed_hosts = [...]：配置允许的主机名列表。
⚝ 静态资源文件：将静态资源文件（例如 CSS, JavaScript, images）复制到合适的目录，并在 Kore 应用中配置静态资源路由。
⚝ 模板文件：将模板文件复制到合适的目录，并在 Kore 应用中配置模板文件路径。
④ 进程管理：
为了保证 Kore Web 应用在生产环境中长期稳定运行，需要使用 进程管理工具（Process Manager）来管理 Kore 应用进程。常用的 进程管理工具 包括：
⚝ systemd：https://systemd.io/
systemd 是现代 Linux 发行版常用的系统和服务管理器，功能强大，配置灵活，支持服务自启动、自动重启、日志管理等功能。
⚝ Supervisor：http://supervisord.org/
Supervisor 是一个用 Python 编写的进程管理工具，轻量级，易于使用，适用于管理多个进程。
⚝ PM2：https://pm2.keymetrics.io/ (虽然 PM2 主要用于 Node.js 应用，但也可以管理其他类型的进程)
使用 systemd 管理 Kore 应用的示例 (创建 systemd 服务单元文件 /etc/systemd/system/kore-app.service)：
1
[Unit]
2
Description=Kore Web Application
3
After=network.target
4
5
[Service]
6
WorkingDirectory=/path/to/your/app/directory # 应用工作目录
7
ExecStart=/usr/local/bin/your-kore-app -f config/kore.conf # Kore 应用可执行文件路径和配置文件路径
8
Restart=on-failure # 进程失败时自动重启
9
User=www-data # 运行用户 (根据实际情况调整)
10
Group=www-data # 运行用户组 (根据实际情况调整)
11
12
[Install]
13
WantedBy=multi-user.target
然后使用 systemctl 命令管理 Kore 应用服务：
1
sudo systemctl enable kore-app.service # 设置开机自启动
2
sudo systemctl start kore-app.service # 启动服务
3
sudo systemctl status kore-app.service # 查看服务状态
4
sudo systemctl stop kore-app.service # 停止服务
5
sudo systemctl restart kore-app.service # 重启服务
⑤ 日志管理：
配置完善的日志管理系统，收集和分析 Kore 应用的访问日志、错误日志、系统日志等，用于监控应用运行状态、排查故障、安全审计等。可以使用日志管理工具，例如 logrotate (日志轮转), rsyslog 或 Fluentd (日志收集和转发)。
⑥ 监控与告警：
配置监控系统，监控 Kore Web 应用的性能指标（例如响应时间、吞吐量、错误率、 CPU 使用率、 内存 使用率等）和服务器资源使用情况。设置告警规则，当监控指标超过阈值时，及时发出告警通知，以便快速响应和处理问题。常用的监控工具有 Prometheus、 Grafana、 Zabbix、 Nagios 等。
⑦ 持续集成/持续部署 (CI/CD)：
采用 CI/CD 流程，自动化 Kore Web 应用的构建、测试和部署过程，提高部署效率和质量，降低部署风险。可以使用 CI/CD 工具，例如 Jenkins、 GitLab CI、 GitHub Actions、 Travis CI 等。
通过以上步骤，可以将 Kore Web 应用安全可靠地部署到生产环境，并进行有效的管理和监控，保证应用的稳定运行和高质量服务。
Chapter 8 深入探讨了 Kore Web 应用的测试与部署，包括单元测试、集成测试、性能测试和生产环境部署。掌握这些内容可以帮助开发者构建高质量、高性能、可靠的 Kore Web 应用，并顺利地将其发布到生产环境。在接下来的章节中，我们将学习 Kore 的高级主题和案例研究。
9. chapter 9： Kore 高级主题 🌟
9.1 自定义中间件 (Custom Middleware) 🛠️
自定义中间件（Custom Middleware）是 Kore Web 框架提供的高级特性之一，允许开发者根据自身应用的需求，编写特定的 中间件 组件，扩展框架的功能，定制请求处理流程。自定义中间件 可以用于处理各种横切关注点的问题，例如：
① 请求日志记录（Request Logging）：记录详细的请求信息，例如请求时间、客户端 IP 地址、请求头、请求体等，用于监控、审计和问题排查。
② 安全增强（Security Enhancement）：实现自定义的安全策略，例如 IP 白名单 限制、 DDoS 防护、自定义 身份验证 和 授权 逻辑等。
③ 请求预处理（Request Preprocessing）：在请求到达处理器之前，对请求进行预处理，例如请求头标准化、请求体数据解密、请求参数转换等。
④ 响应后处理（Response Postprocessing）：在响应发送到客户端之后，对响应进行后处理，例如添加自定义响应头、压缩响应体、记录响应日志等。
⑤ 自定义错误处理（Custom Error Handling）：捕获和处理特定类型的错误，例如自定义 404 页面、全局异常处理等。
9.1.1 编写自定义中间件
编写 自定义中间件 函数需要遵循 Kore 中间件函数的规范，函数原型如下：
1
int middleware_function(struct http_request *req, void *arg);
参数说明：
req：指向struct http_request对象的指针，表示当前的 HTTP 请求。arg：用户自定义参数，在注册中间件时传递。
返回值：
KORE_RESULT_OK：表示中间件处理成功，继续传递请求到下一个中间件或处理器。KORE_RESULT_ERROR：表示中间件处理失败，终止请求处理流程，并返回错误响应。
在中间件函数内部，可以访问和修改 struct http_request 对象，执行自定义的逻辑，并根据处理结果返回相应的状态码。
9.1.2 注册自定义中间件
自定义中间件 可以注册为 全局中间件 或 路由中间件，使用不同的注册函数。
① 注册全局中间件：
使用 kore_http_middleware_register() 函数注册 全局中间件。全局中间件 会应用于所有 HTTP 请求。
1
int my_global_middleware(struct http_request *req, void *arg);
2
3
int
4
kore_main(int argc, char *argv[])
5
{
6
kore_http_middleware_register(my_global_middleware, NULL); // 注册全局中间件
7
// ... 其他代码
8
return (KORE_RESULT_OK);
9
}
10
11
int
12
my_global_middleware(struct http_request *req, void *arg)
13
{
14
kore_log(LOG_INFO, "Global middleware executed for path: %s", req->path);
15
// ... 自定义中间件逻辑
16
return (KORE_RESULT_OK); // 继续传递请求
17
}
② 注册路由中间件：
使用 kore_http_handler_add_middleware() 函数注册 路由中间件。路由中间件 只会应用于特定的路由规则。
1
int my_route_middleware(struct http_request *req, void *arg);
2
int my_handler(struct http_request *req);
3
4
int
5
kore_main(int argc, char *argv[])
6
{
7
kore_http_handler_add_middleware("/api/users", my_route_middleware, my_handler); // 注册路由中间件
8
// ... 其他代码
9
return (KORE_RESULT_OK);
10
}
11
12
int
13
my_route_middleware(struct http_request *req, void *arg)
14
{
15
kore_log(LOG_INFO, "Route middleware executed for path: %s", req->path);
16
// ... 自定义中间件逻辑
17
return (KORE_RESULT_OK); // 继续传递请求
18
}
19
20
int
21
my_handler(struct http_request *req)
22
{
23
http_response(req, 200, "Hello from handler", 18);
24
return (KORE_RESULT_OK);
25
}
9.1.3 自定义中间件示例：请求日志记录
以下示例展示如何编写一个 自定义中间件，用于记录每个 HTTP 请求 的详细信息。
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <time.h>
4
5
int request_logger_middleware(struct http_request *, void *);
6
7
int
8
request_logger_middleware(struct http_request *req, void *arg)
9
{
10
time_t timer;
11
char buffer[26];
12
struct tm* tm_info;
13
14
time(&timer);
15
tm_info = localtime(&timer);
16
strftime(buffer, 26, "%Y-%m-%d %H:%M:%S", tm_info);
17
18
kore_log(LOG_INFO, "[%s] %s %s - Client IP: %s, User-Agent: %s",
19
buffer, req->method_str, req->path, req->client_ip, http_request_header(req, "User-Agent"));
20
21
return (KORE_RESULT_OK); // 继续传递请求
22
}
23
24
int
25
kore_main(int argc, char *argv[])
26
{
27
kore_http_middleware_register(request_logger_middleware, NULL); // 注册为全局中间件
28
// ... 其他代码
29
return (KORE_RESULT_OK);
30
}
这个 request_logger_middleware 中间件会在每个请求到达时被调用，记录请求的时间、请求方法、请求路径、客户端 IP 地址和 User-Agent 头部信息。
9.1.4 自定义中间件示例：IP 白名单限制
以下示例展示如何编写一个 自定义中间件，用于实现 IP 白名单 限制，只允许来自白名单 IP 地址的请求访问应用。
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <string.h>
4
5
// 假设的 IP 白名单列表 (实际应用中可以从配置文件或数据库加载)
6
const char *allowed_ips[] = {
7
"127.0.0.1",
8
"192.168.1.100",
9
NULL // 列表结束标志
10
};
11
12
int ip_whitelist_middleware(struct http_request *, void *);
13
int is_ip_allowed(const char *ip); // 声明 IP 地址检查函数
14
15
int
16
ip_whitelist_middleware(struct http_request *req, void *arg)
17
{
18
if (!is_ip_allowed(req->client_ip)) {
19
kore_log(LOG_WARNING, "Access denied from IP: %s", req->client_ip);
20
http_response_error(req, 403); // Forbidden
21
return (KORE_RESULT_ERROR); // 终止请求
22
}
23
return (KORE_RESULT_OK); // 继续传递请求
24
}
25
26
int
27
is_ip_allowed(const char *ip)
28
{
29
for (int i = 0; allowed_ips[i] != NULL; i++) {
30
if (strcmp(ip, allowed_ips[i]) == 0) {
31
return 1; // IP 地址在白名单中
32
}
33
}
34
return 0; // IP 地址不在白名单中
35
}
36
37
int
38
kore_main(int argc, char *argv[])
39
{
40
kore_http_middleware_register(ip_whitelist_middleware, NULL); // 注册为全局中间件
41
// ... 其他代码
42
return (KORE_RESULT_OK);
43
}
这个 ip_whitelist_middleware 中间件会在每个请求到达时被调用，检查客户端 IP 地址是否在白名单列表中。如果不在白名单中，则返回 403 Forbidden 错误，拒绝访问。
9.2 Kore 扩展开发 (Extending Kore) 🧩
Kore Web 框架具有良好的 可扩展性（Extensibility），允许开发者通过多种方式扩展框架的功能，满足特定的需求。
① 自定义中间件 (已在 9.1 节介绍)：
自定义中间件 是最常见的扩展 Kore 功能的方式。通过编写 自定义中间件，可以扩展请求处理流程，添加各种横切关注点的功能。
② C 扩展模块 (C Extension Modules)：
Kore 允许开发者编写 C 扩展模块，将自定义的 C 代码 编译成 动态链接库（Dynamic Link Library, DLL），并在 Kore 应用中加载和使用。C 扩展模块 可以用于实现性能敏感的功能、集成第三方 C 库、扩展 Kore 的 API 等。
编写 C 扩展模块 的步骤：
1
1. **创建 C 源代码文件**：编写 **C 代码**，实现扩展模块的功能。需要包含 Kore 提供的头文件 `<kore.h>`，并遵循 Kore 扩展模块的 **API** 规范。
2
2. **定义模块初始化函数**：每个 **C 扩展模块** 需要定义一个 **模块初始化函数**，函数名为 `kore_module_init()`，用于模块的初始化操作。
3
3. **编译 C 代码**：将 **C 源代码** 编译成 **动态链接库** (`.so` 文件，Linux/macOS) 或 (`.dll` 文件，Windows)。编译时需要链接 Kore 库。
4
4. **配置 Kore 加载扩展模块**：在 `kore.conf` 配置文件中，使用 `module` 指令配置要加载的 **C 扩展模块** 的路径。
示例 kore.conf 配置：
1
module "/path/to/my_extension.so"
示例 C 扩展模块 代码 (my_extension.c)：
1
#include <kore.h>
2
3
int my_extension_handler(struct http_request *);
4
5
int
6
kore_module_init(int argc, char *argv[])
7
{
8
kore_log(LOG_INFO, "My C extension module initialized");
9
kore_http_handler_add("/extension", my_extension_handler); // 注册一个处理器
10
return (KORE_RESULT_OK);
11
}
12
13
int
14
my_extension_handler(struct http_request *req)
15
{
16
http_response(req, 200, "Hello from C extension!", 23);
17
return (KORE_RESULT_OK);
18
}
编译 C 扩展模块 (假设 Makefile 中已经配置了 Kore 的 include 路径和库链接)：
1
# Makefile for C extension module
2
EXTENSION_MODULE_NAME = my_extension
3
EXTENSION_MODULE_SRC = my_extension.c
4
EXTENSION_MODULE_OBJ = $(EXTENSION_MODULE_SRC:.c=.o)
5
EXTENSION_MODULE_LIB = $(EXTENSION_MODULE_NAME).so
6
CFLAGS = -fPIC -shared -Wall -Wextra -Werror -g -I/usr/local/include # 根据 Kore 安装路径调整 include 路径
7
LIBS = -lkore -lssl -lcrypto -lpcre -lz # 根据 Kore 依赖调整库
8
9
$(EXTENSION_MODULE_LIB): $(EXTENSION_MODULE_OBJ)
10
$(CC) $(CFLAGS) -o $(EXTENSION_MODULE_LIB) $(EXTENSION_MODULE_OBJ) $(LIBS)
11
12
%.o: %.c
13
$(CC) $(CFLAGS) -c $< -o $@
14
15
all: $(EXTENSION_MODULE_LIB)
16
17
clean:
18
rm -f $(EXTENSION_MODULE_LIB) $(EXTENSION_MODULE_OBJ)
19
20
.PHONY: all clean
编译命令： make
编译成功后，会生成 my_extension.so 文件。将该文件路径配置到 kore.conf 的 module 指令中，Kore 应用启动时就会加载该 C 扩展模块，并注册 /extension 路由。
③ 自定义事件类型和事件处理器：
Kore 的核心架构是 事件驱动 的。开发者可以扩展 Kore 的事件系统，定义 自定义事件类型 和 事件处理器，实现更灵活的异步处理逻辑。
扩展 Kore 事件系统的步骤：
1
1. **定义自定义事件类型**：在代码中定义新的事件类型常量。
2
2. **创建自定义事件**：使用 `kore_event_create()` 函数创建 **自定义事件** 对象，并设置事件类型和相关数据。
3
3. **注册自定义事件处理器**：使用 `kore_event_handler_register()` 函数注册 **自定义事件处理器** 函数，将事件类型与处理函数关联起来。
4
4. **触发自定义事件**：在需要触发事件的地方，使用 `kore_event_signal()` 函数触发 **自定义事件**。
示例代码（伪代码，仅供参考）：
1
// 定义自定义事件类型
2
#define MY_CUSTOM_EVENT_TYPE 1000
3
4
// 自定义事件处理器函数
5
void my_custom_event_handler(struct kore_event *);
6
7
int
8
kore_main(int argc, char *argv[])
9
{
10
// 注册自定义事件处理器
11
kore_event_handler_register(MY_CUSTOM_EVENT_TYPE, my_custom_event_handler);
12
// ... 其他代码
13
return (KORE_RESULT_OK);
14
}
15
16
void
17
my_custom_event_handler(struct kore_event *ev)
18
{
19
kore_log(LOG_INFO, "Custom event handler called, event type: %d", ev->type);
20
// ... 自定义事件处理逻辑
21
}
22
23
// 在需要触发事件的地方
24
void trigger_custom_event() {
25
struct kore_event *ev = kore_event_create(MY_CUSTOM_EVENT_TYPE);
26
// ... 设置事件数据 (可选)
27
kore_event_signal(ev); // 触发自定义事件
28
}
通过扩展 Kore 的事件系统，可以实现更复杂的异步任务处理、后台任务调度、自定义协议支持等高级功能。
9.3 性能优化 (Performance Optimization) 🚀
性能优化（Performance Optimization）是 Web 应用开发中的重要环节，尤其对于高负载、高并发的应用，性能优化至关重要。Kore Web 框架本身就以高性能著称，但在实际应用开发中，仍然可以通过一些策略进一步优化性能。
① 代码优化：
⚝ 算法和数据结构优化：选择合适的算法和数据结构，降低时间复杂度和空间复杂度。
⚝ 减少内存分配和释放：频繁的内存分配和释放会降低性能。尽量重用对象、使用 内存池（Memory Pool）等技术，减少内存操作开销。
⚝ 避免不必要的字符串操作：字符串操作通常比较耗时。尽量减少不必要的字符串复制、拼接、格式化等操作。
⚝ 内联函数 (inline functions)：对于频繁调用的短小函数，可以使用 inline 关键字声明为 内联函数，减少函数调用开销。
⚝ 编译优化：使用编译器优化选项（例如 -O2, -O3）进行编译，提高代码执行效率。
② 数据库优化：
⚝ 索引优化：为经常用于查询条件的列创建 索引（Index），提高查询速度。
⚝ 查询语句优化：优化 SQL 查询语句，避免全表扫描、使用合适的 JOIN 类型、减少不必要的数据返回等。
⚝ 连接池（Connection Pooling）：使用 数据库连接池 复用数据库连接，减少连接建立和关闭的开销。
⚝ 缓存：使用 缓存 缓存 frequently accessed database data，减少数据库访问次数。
③ 缓存策略 (已在 4.3 节介绍)：
合理使用 缓存 是提高 Web 应用性能的关键策略。选择合适的 缓存类型（例如内存缓存、分布式缓存）、 缓存策略（例如 Cache-Aside, Read-Through, Write-Through, Write-Back）、 缓存失效策略（例如 TTL (Time-To-Live), LRU (Least Recently Used)）等，可以有效提高性能。
④ HTTP 优化：
⚝ HTTP 压缩（HTTP Compression）：启用 HTTP 压缩（例如 gzip, Brotli）压缩响应内容，减少网络传输量，提高页面加载速度。Kore 默认支持 gzip 压缩，可以通过 kore.conf 配置启用。
⚝ 静态资源缓存（Static Asset Caching）：对于静态资源文件（例如 CSS, JavaScript, images），配置 HTTP 缓存 头部（例如 Cache-Control, Expires），利用浏览器缓存和 CDN 缓存，减少服务器负载和网络延迟。
⚝ CDN 加速（Content Delivery Network, CDN）：使用 CDN 分发静态资源，将静态资源缓存到全球各地的 CDN 节点，加速用户访问速度，并减轻源站服务器的压力。
⚝ Keep-Alive 连接（Keep-Alive Connection）：启用 HTTP Keep-Alive，复用 TCP 连接，减少连接建立和关闭的开销，提高连接效率。Kore 默认启用 Keep-Alive。
⚝ HTTP/2 协议：启用 HTTP/2 协议，利用 HTTP/2 的多路复用、头部压缩等特性，提高 HTTP 通信效率。Kore 支持 HTTP/2。
⑤ 异步和并发优化 (已在 5.1 和 5.2 节介绍)：
充分利用 Kore 的 异步非阻塞 I/O 和 多进程模型，编写高效的异步代码，提高并发处理能力，是提高 Kore Web 应用性能的重要手段。
⑥ 负载均衡和反向代理 (已在 8.4 节部署部分提及)：
使用 负载均衡 和 反向代理 服务器（例如 Nginx, HAProxy）可以将请求分发到多台 Kore 服务器，提高系统的整体处理能力和 高可用性（High Availability）。 反向代理 还可以作为静态资源服务器和缓存服务器，进一步提高性能。
⑦ 性能监控和分析：
使用性能监控工具（例如 Profiling 工具、 APM (Application Performance Monitoring) 系统）监控 Kore Web 应用的性能指标，分析性能瓶颈，找到性能优化的重点。常用的 C 语言 Profiling 工具 包括 gprof, perf, Valgrind 等。
9.4 与其他技术的集成 (Integration with other technologies) 🤝
Kore Web 框架可以与其他各种技术进行集成，扩展其功能，构建更完善的 Web 应用系统。
① 前端技术集成：
Kore 作为后端框架，可以与各种前端技术进行集成，构建 前后端分离 的 Web 应用。常见的前端技术包括：
⚝ HTML/CSS/JavaScript：构建传统 Web 页面（Server-Side Rendering, SSR）或 单页应用（Single-Page Application, SPA）。
⚝ 前端框架/库：例如 React, Vue.js, Angular 等，构建复杂的 SPA 应用。
⚝ WebSocket 前端库：例如 Socket.IO, ws (JavaScript WebSocket library)，构建 实时应用。
Kore 可以提供 RESTful API 或 GraphQL API，供前端应用调用。也可以使用 Kore 的 模板引擎 生成 HTML 页面。
② 数据库技术集成 (已在 4.1 节介绍)：
Kore 可以与多种 关系型数据库（例如 PostgreSQL, MySQL, SQLite3）集成，进行数据存储和管理。也可以与其他类型的数据库集成，例如 NoSQL 数据库（例如 MongoDB, Redis, Cassandra），根据应用需求选择合适的数据库技术。
③ 缓存技术集成 (已在 4.3 节和 9.3 节介绍)：
Kore 可以与各种 缓存系统（例如 Redis, Memcached）集成，提高应用性能。
④ 消息队列技术集成：
Kore 可以与 消息队列（Message Queue, MQ）系统（例如 RabbitMQ, Kafka, Redis Pub/Sub）集成，实现异步任务处理、消息推送、分布式系统组件解耦等功能。可以使用 C 语言 MQ 客户端库 连接到 MQ 服务器，并使用 Kore 的异步 API 处理消息。
⑤ 搜索引擎技术集成：
Kore 可以与 搜索引擎（例如 Elasticsearch, Solr）集成，实现全文搜索、日志分析、数据索引等功能. 可以使用 C 语言 Elasticsearch 客户端库 或 Solr Client Library for C 连接到 搜索引擎服务器，并使用 HTTP API 进行数据交互。
⑥ 云服务集成：
Kore Web 应用可以部署到各种 云计算平台（例如 AWS, Azure, GCP），并与云平台提供的各种 云服务 集成，例如：
* 云数据库（Cloud Database）：使用云平台提供的托管数据库服务，例如 Amazon RDS, Azure Database for PostgreSQL, Google Cloud SQL。
* 云缓存（Cloud Cache）：使用云平台提供的托管缓存服务，例如 Amazon ElastiCache, Azure Cache for Redis, Google Cloud Memorystore。
* 云存储（Cloud Storage）：使用云平台提供的对象存储服务，例如 Amazon S3, Azure Blob Storage, Google Cloud Storage，存储静态资源和用户上传的文件。
* 云监控（Cloud Monitoring）：使用云平台提供的监控服务，监控 Kore Web 应用和服务器的性能指标和运行状态，例如 Amazon CloudWatch, Azure Monitor, Google Cloud Monitoring。
* 云日志（Cloud Logging）：使用云平台提供的日志服务，收集和分析 Kore Web 应用的日志，例如 Amazon CloudWatch Logs, Azure Monitor Logs, Google Cloud Logging。
⑦ 微服务架构集成：
在 微服务架构 中，Kore 可以作为构建 微服务 的框架，与其他微服务框架和技术（例如 Docker, Kubernetes, Service Mesh）集成，构建分布式、可扩展的微服务系统。
Chapter 9 深入探讨了 Kore Web 框架的高级主题，包括自定义中间件、Kore 扩展开发、性能优化以及与其他技术的集成。掌握这些高级主题可以帮助开发者更深入地理解和应用 Kore Web 框架，构建更复杂、高性能、可扩展的 Web 应用系统。在接下来的章节中，我们将通过案例研究，展示 Kore Web 框架在实际项目中的应用。
10. chapter 10： 案例研究 (Case Studies) 💡
本章节将通过几个案例研究，展示 Kore Web 框架在实际项目中的应用，涵盖不同类型的 Web 应用场景，并重点突出 Kore 的优势和特点。
10.1 构建 RESTful API 🌐
RESTful API（Representational State Transferful Application Programming Interface）是一种常用的 Web API 设计风格，用于构建可扩展、易于维护的 Web 服务。Kore Web 框架非常适合构建高性能的 RESTful API 服务。
10.1.1 案例背景：用户管理 API
假设我们需要构建一个用户管理 RESTful API，提供以下功能：
① 获取用户列表
② 根据 ID 获取单个用户信息
③ 创建新用户
④ 更新用户信息
⑤ 删除用户
10.1.2 软件架构
该 API 服务采用经典的三层架构：
1
graph LR
2
A[客户端 (Client)] --> B(Kore Web 应用 - API 层)
3
B --> C(业务逻辑层)
4
C --> D(数据访问层)
5
D --> E[数据库 (Database)]
- API 层：使用 Kore Web 框架构建，负责接收 HTTP 请求，路由请求到相应的 处理器，处理请求和响应的格式转换（例如 JSON 序列化和反序列化）。
- 业务逻辑层：负责处理业务逻辑，例如用户数据验证、权限控制等。
- 数据访问层 (DAL)：封装数据库操作，提供 API 供业务逻辑层调用，实现数据持久化。
- 数据库：存储用户数据，例如 PostgreSQL, MySQL 等。
10.1.3 API 设计与实现
① 路由设计：
| 方法 | 路径 | 功能描述 |
|---|---|---|
| GET | /users | 获取用户列表 |
| GET | /users/{id} | 根据 ID 获取用户信息 |
| POST | /users | 创建新用户 |
| PUT | /users/{id} | 更新用户信息 |
| DELETE | /users/{id} | 删除用户 |
② 处理器实现 (示例代码，src/handlers/users.c)：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <json.h>
4
#include "models/user.h" // 假设用户数据模型定义在 user.h/user.c 中
5
6
int users_list_handler(struct http_request *);
7
int users_get_handler(struct http_request *);
8
int users_create_handler(struct http_request *);
9
int users_update_handler(struct http_request *);
10
int users_delete_handler(struct http_request *);
11
12
int
13
users_list_handler(struct http_request *req)
14
{
15
struct User *users = NULL; // 假设 user_list() 函数返回用户列表
16
size_t user_count = 0;
17
18
user_list(&users, &user_count); // 从数据访问层获取用户列表
19
20
struct json_value *root = json_array();
21
for (size_t i = 0; i < user_count; i++) {
22
json_array_push(root, user_to_json(&users[i])); // user_to_json() 将 User 对象转换为 JSON
23
}
24
25
http_response_header(req, "Content-Type", "application/json");
26
http_response_json(req, 200, root);
27
json_value_free(root);
28
user_list_free(users, user_count); // 释放用户列表内存
29
return (KORE_RESULT_OK);
30
}
31
32
int
33
users_get_handler(struct http_request *req)
34
{
35
const char *id_str = http_request_path_parameter(req, "id");
36
int user_id = atoi(id_str);
37
struct User *user = user_get_by_id(user_id); // 从数据访问层获取用户信息
38
39
if (user == NULL) {
40
http_response_error(req, 404); // Not Found
41
return (KORE_RESULT_ERROR);
42
}
43
44
http_response_header(req, "Content-Type", "application/json");
45
http_response_json(req, 200, user_to_json(user));
46
user_free(user); // 释放用户对象内存
47
return (KORE_RESULT_OK);
48
}
49
50
int
51
users_create_handler(struct http_request *req)
52
{
53
struct json_value *body = http_request_body_json(req); // 解析 JSON 请求体
54
if (body == NULL || body->type != JSON_OBJECT) {
55
http_response_error(req, 400); // Bad Request
56
return (KORE_RESULT_ERROR);
57
}
58
59
struct User user;
60
if (user_from_json(&user, body) != KORE_RESULT_OK) { // user_from_json() 从 JSON 对象创建 User 对象
61
http_response_error(req, 400); // Bad Request, JSON 数据格式错误
62
json_value_free(body);
63
return (KORE_RESULT_ERROR);
64
}
65
66
if (user_create(&user) != KORE_RESULT_OK) { // 调用数据访问层创建用户
67
http_response_error(req, 500); // Internal Server Error
68
json_value_free(body);
69
return (KORE_RESULT_ERROR);
70
}
71
72
http_response_header(req, "Content-Type", "application/json");
73
http_response_status(req, 201); // Created
74
http_response_json(req, 201, user_to_json(&user));
75
json_value_free(body);
76
user_free(&user); // 释放用户对象内存
77
return (KORE_RESULT_OK);
78
}
79
80
// ... users_update_handler, users_delete_handler 的实现 (类似 users_create_handler)
81
82
int
83
kore_main(int argc, char *argv[])
84
{
85
kore_http_handler_add("/users", users_list_handler);
86
kore_http_handler_add("/users/<id>", users_get_handler);
87
kore_http_handler_add("/users", users_create_handler);
88
kore_http_handler_add("/users/<id>", users_update_handler);
89
kore_http_handler_add("/users/<id>", users_delete_handler);
90
return (KORE_RESULT_OK);
91
}
③ 数据模型和数据访问层 (示例代码，src/models/user.c)：
1
#include "user.h"
2
#include <kore.h>
3
#include <kore/database.h>
4
#include <json.h>
5
#include <stdlib.h>
6
#include <string.h>
7
8
// User 结构体定义 (user.h)
9
struct User {
10
int id;
11
char *username;
12
char *email;
13
};
14
15
// user_list 函数实现 (user.c)
16
int
17
user_list(struct User **users_ptr, size_t *count_ptr)
18
{
19
struct kore_database *db;
20
struct kore_db_result *result = NULL;
21
struct User *users = NULL;
22
size_t count = 0;
23
int ret = KORE_RESULT_OK;
24
25
db = kore_database_get("mydb"); // 获取数据库连接
26
if (db == NULL) {
27
return KORE_RESULT_ERROR;
28
}
29
30
result = kore_database_query(db, "SELECT id, username, email FROM users");
31
if (result == NULL) {
32
return KORE_RESULT_ERROR;
33
}
34
35
while (kore_database_result_next_row(result)) {
36
count++;
37
}
38
kore_database_result_reset(result); // 重置结果集游标
39
40
if (count > 0) {
41
users = kore_malloc(sizeof(struct User) * count);
42
if (users == NULL) {
43
kore_database_result_free(result);
44
return KORE_RESULT_ERROR;
45
}
46
47
size_t i = 0;
48
while (kore_database_result_next_row(result)) {
49
users[i].id = kore_database_result_get_integer(result, 0);
50
users[i].username = kore_strdup(kore_database_result_get_string(result, 1));
51
users[i].email = kore_strdup(kore_database_result_get_string(result, 2));
52
i++;
53
}
54
}
55
56
kore_database_result_free(result);
57
*users_ptr = users;
58
*count_ptr = count;
59
return ret;
60
}
61
62
// user_get_by_id 函数实现 (user.c)
63
struct User *
64
user_get_by_id(int id)
65
{
66
struct kore_database *db;
67
struct kore_db_result *result = NULL;
68
struct User *user = NULL;
69
70
db = kore_database_get("mydb");
71
if (db == NULL) {
72
return NULL;
73
}
74
75
result = kore_database_query(db, "SELECT id, username, email FROM users WHERE id = $1", id);
76
if (result == NULL || !kore_database_result_next_row(result)) {
77
goto cleanup;
78
}
79
80
user = kore_malloc(sizeof(struct User));
81
user->id = kore_database_result_get_integer(result, 0);
82
user->username = kore_strdup(kore_database_result_get_string(result, 1));
83
user->email = kore_strdup(kore_database_result_get_string(result, 2));
84
85
cleanup:
86
if (result != NULL) {
87
kore_database_result_free(result);
88
}
89
return user;
90
}
91
92
// user_create 函数实现 (user.c)
93
int
94
user_create(struct User *user)
95
{
96
struct kore_database *db;
97
db = kore_database_get("mydb");
98
if (db == NULL) {
99
return KORE_RESULT_ERROR;
100
}
101
if (kore_database_query(db, "INSERT INTO users (username, email) VALUES ($1, $2)", user->username, user->email) == NULL) {
102
return KORE_RESULT_ERROR;
103
}
104
return KORE_RESULT_OK;
105
}
106
107
// user_update, user_delete 函数实现 (类似 user_create)
108
109
// user_to_json 函数实现 (user.c)
110
struct json_value *
111
user_to_json(struct User *user)
112
{
113
struct json_value *json_user = json_object();
114
json_object_push(json_user, "id", json_integer(user->id));
115
json_object_push(json_user, "username", json_string(user->username));
116
json_object_push(json_user, "email", json_string(user->email));
117
return json_user;
118
}
119
120
// user_from_json 函数实现 (user.c)
121
int
122
user_from_json(struct User *user, struct json_value *json_user)
123
{
124
struct json_object_entry *entry;
125
json_object_rewind(json_user);
126
while ((entry = json_object_next(json_user))) {
127
if (strcmp(entry->name, "username") == 0 && entry->value->type == JSON_STRING) {
128
user->username = kore_strdup(json_string_value(entry->value));
129
} else if (strcmp(entry->name, "email") == 0 && entry->value->type == JSON_STRING) {
130
user->email = kore_strdup(json_string_value(entry->value));
131
}
132
// ... 其他字段处理
133
}
134
return KORE_RESULT_OK;
135
}
136
137
// user_free 函数实现 (user.c)
138
void
139
user_free(struct User *user)
140
{
141
if (user != NULL) {
142
kore_free(user->username);
143
kore_free(user->email);
144
kore_free(user);
145
}
146
}
147
148
// user_list_free 函数实现 (user.c)
149
void
150
user_list_free(struct User *users, size_t count)
151
{
152
if (users != NULL) {
153
for (size_t i = 0; i < count; i++) {
154
user_free(&users[i]);
155
}
156
kore_free(users);
157
}
158
}
10.1.4 实践总结
通过 Kore Web 框架构建 RESTful API，可以充分利用 Kore 的高性能和简洁性，快速开发出高效、稳定的 API 服务。在实际开发中，还需要考虑：
- 身份验证和授权：保护 API 接口，防止未授权访问。
- 输入验证：对请求数据进行严格验证，防止恶意输入。
- 错误处理：提供友好的错误响应，方便客户端调试。
- API 文档：编写清晰的 API 文档，方便客户端开发者使用。
- 性能优化：根据实际负载情况进行性能优化，例如缓存、数据库优化等。
10.2 构建实时应用 💬
实时应用（Real-time Application）需要服务器和客户端之间进行 双向实时通信，例如在线聊天、实时数据推送、多人在线游戏等。Kore Web 框架对 WebSocket 协议的原生支持，使其非常适合构建实时应用。
10.2.1 案例背景：在线聊天室
构建一个简单的在线聊天室应用，用户可以连接到聊天室，发送和接收消息，实时与其他用户交流。
10.2.2 软件架构
1
graph LR
2
A[客户端 (Web/App)] --> B(Kore Web 应用 - WebSocket 服务)
3
B --> C(消息处理模块)
- Kore Web 应用 - WebSocket 服务：使用 Kore Web 框架构建，监听 WebSocket 连接请求，处理 WebSocket 消息的接收和发送，维护 WebSocket 连接列表。
- 消息处理模块：负责处理聊天消息的逻辑，例如消息广播、用户管理、消息持久化（可选）。
10.2.3 实现关键点
① WebSocket 连接处理 (示例代码，src/handlers/chat.c)：
1
#include <kore.h>
2
#include <kore/http.h>
3
#include <uthash.h> // 引入 uthash 库，用于管理 WebSocket 连接
4
5
// WebSocket 连接信息结构
6
struct chat_connection {
7
struct websocket *ws;
8
char *username;
9
UT_hash_handle hh;
10
};
11
12
struct chat_connection *connections = NULL; // 全局 WebSocket 连接哈希表
13
14
void chat_connection_add(struct websocket *ws, const char *username);
15
void chat_connection_remove(struct websocket *ws);
16
void chat_broadcast_message(const char *message, struct websocket *sender_ws);
17
void websocket_message_cb(struct websocket *, uint8_t, void *, size_t);
18
void websocket_close_cb(struct websocket *);
19
20
int
21
chat_websocket_handler(struct http_request *req)
22
{
23
if (!http_request_is_websocket(req)) {
24
http_response_error(req, 400);
25
return (KORE_RESULT_ERROR);
26
}
27
28
int ret = http_websocket_handshake(req, NULL);
29
if (ret != KORE_RESULT_OK) {
30
http_response_error(req, 500);
31
return (KORE_RESULT_ERROR);
32
}
33
34
struct websocket *ws = req->websocket;
35
websocket_set_message_callback(ws, websocket_message_cb);
36
websocket_set_close_callback(ws, websocket_close_cb);
37
38
// 假设从请求参数中获取用户名
39
const char *username = http_request_query_parameter(req, "username");
40
if (username == NULL) {
41
username = "Anonymous";
42
}
43
chat_connection_add(ws, username); // 添加到连接列表
44
45
kore_log(LOG_INFO, "WebSocket connection established for user: %s", username);
46
return (KORE_RESULT_OK);
47
}
48
49
// 添加 WebSocket 连接到全局哈希表
50
void
51
chat_connection_add(struct websocket *ws, const char *username)
52
{
53
struct chat_connection *conn = kore_malloc(sizeof(struct chat_connection));
54
conn->ws = ws;
55
conn->username = kore_strdup(username);
56
HASH_ADD_PTR(connections, ws, conn); // 使用 websocket 指针作为 key
57
chat_broadcast_message("User joined: ", ws); // 广播用户加入消息
58
}
59
60
// 从全局哈希表移除 WebSocket 连接
61
void
62
chat_connection_remove(struct websocket *ws)
63
{
64
struct chat_connection *conn = NULL;
65
HASH_FIND_PTR(connections, &ws, conn); // 使用 websocket 指针查找
66
if (conn) {
67
chat_broadcast_message("User left: ", ws); // 广播用户离开消息
68
HASH_DEL(connections, conn);
69
kore_free(conn->username);
70
kore_free(conn);
71
}
72
}
73
74
// WebSocket 消息接收回调函数
75
void
76
websocket_message_cb(struct websocket *ws, uint8_t op, void *data, size_t len)
77
{
78
if (op == WEBSOCKET_OP_TEXT) {
79
struct chat_connection *conn = NULL;
80
HASH_FIND_PTR(connections, &ws, conn);
81
if (conn) {
82
char message_buffer[1024]; // 消息缓冲区
83
snprintf(message_buffer, sizeof(message_buffer), "%s: %.*s", conn->username, (int)len, (char *)data);
84
chat_broadcast_message(message_buffer, ws); // 广播消息
85
}
86
}
87
}
88
89
// WebSocket 关闭回调函数
90
void
91
websocket_close_cb(struct websocket *ws)
92
{
93
chat_connection_remove(ws); // 从连接列表移除
94
kore_log(LOG_INFO, "WebSocket connection closed");
95
}
96
97
// 广播消息到所有连接的客户端 (除了发送者)
98
void
99
chat_broadcast_message(const char *message, struct websocket *sender_ws)
100
{
101
struct chat_connection *conn, *tmp;
102
char *full_message;
103
size_t message_len;
104
105
message_len = strlen(message);
106
full_message = kore_malloc(message_len + 1);
107
strcpy(full_message, message);
108
109
110
HASH_ITER(hh, connections, conn, tmp) {
111
if (conn->ws != sender_ws) { // 排除消息发送者
112
websocket_send_message(conn->ws, WEBSOCKET_OP_TEXT, full_message, message_len);
113
}
114
}
115
kore_free(full_message);
116
}
117
118
119
int
120
kore_main(int argc, char *argv[])
121
{
122
kore_websocket_handler_add("/chat", chat_websocket_handler);
123
return (KORE_RESULT_OK);
124
}
② 客户端实现 (JavaScript 示例)：
1
const websocket = new WebSocket("ws://localhost:8888/chat?username=User1"); // 连接 WebSocket 服务
2
3
websocket.onopen = () => {
4
console.log("WebSocket connection opened");
5
};
6
7
websocket.onmessage = (event) => {
8
const message = event.data;
9
console.log("Received message: " + message);
10
// 将消息显示在聊天界面
11
const messageDiv = document.createElement("div");
12
messageDiv.textContent = message;
13
document.getElementById("chat-messages").appendChild(messageDiv);
14
};
15
16
websocket.onclose = () => {
17
console.log("WebSocket connection closed");
18
};
19
20
function sendMessage() {
21
const messageInput = document.getElementById("message-input");
22
const message = messageInput.value;
23
websocket.send(message); // 发送消息
24
messageInput.value = ""; // 清空输入框
25
}
10.2.4 实践总结
使用 Kore Web 框架构建实时应用，可以充分利用 Kore 的 WebSocket 原生支持和高性能 I/O 模型，构建出低延迟、高并发的实时通信服务。在实际开发中，还需要考虑：
- 用户身份验证：验证 WebSocket 连接用户的身份。
- 消息持久化：将聊天消息持久化存储，实现消息记录和回放功能。
- 房间管理：支持创建和管理多个聊天房间，实现群组聊天功能。
- 消息过滤和安全：对聊天消息进行过滤和安全检查，防止恶意信息传播。
- 水平扩展：当用户量增加时，需要考虑如何对 WebSocket 服务进行水平扩展，提高系统容量。
10.3 构建 CMS 系统 📰
CMS（Content Management System，内容管理系统）用于创建、管理和发布网站内容，例如文章、新闻、博客等。Kore Web 框架可以用于构建轻量级、高性能的 CMS 系统。
10.3.1 案例背景： 简易博客系统
构建一个简易的博客系统，提供以下核心功能：
① 文章发布与管理
② 文章分类与标签
③ 用户评论功能
④ 简单的后台管理界面
10.3.2 软件架构
1
graph LR
2
A[客户端 (浏览器)] --> B(Kore Web 应用 - CMS)
3
B --> C(业务逻辑层 - 文章管理, 用户管理, 评论管理)
4
C --> D(数据访问层)
5
D --> E[数据库 (Database)]
6
B --> F[静态资源 (Static Files)]
7
B --> G[模板引擎 (Template Engine)]
- Kore Web 应用 - CMS：使用 Kore Web 框架构建，负责处理 HTTP 请求，路由请求，调用业务逻辑层，渲染页面，处理用户认证和授权。
- 业务逻辑层：包含文章管理、用户管理、评论管理等模块，负责处理 CMS 的核心业务逻辑。
- 数据访问层 (DAL)：封装数据库操作，提供 API 供业务逻辑层调用，实现数据持久化。
- 数据库：存储博客文章、用户信息、评论数据等。
- 静态资源：存储 CSS、 JavaScript、 images 等静态资源文件。
- 模板引擎：用于渲染动态 HTML 页面，例如文章列表页、文章详情页、后台管理页面等。
10.3.3 实现关键点
① 文章发布与管理功能：
- 数据模型：定义文章的数据模型，包括标题、内容、作者、发布时间、分类、标签等字段。
- 后台管理界面：使用 Kore 结合 模板引擎 构建后台管理界面，提供文章发布、编辑、删除等功能。
- 路由设计：设计文章列表页、文章详情页、后台管理页面的路由。
- 处理器实现：编写处理器函数，处理文章列表、文章详情、文章发布、编辑、删除等请求，调用业务逻辑层和数据访问层完成相应操作。
② 用户评论功能：
- 数据模型：定义评论的数据模型，包括评论内容、评论作者、评论时间、所属文章等字段。
- 评论提交表单：在文章详情页添加评论提交表单，允许用户提交评论。
- 评论展示：在文章详情页展示评论列表。
- 处理器实现：编写处理器函数，处理评论提交请求，将评论数据保存到数据库，并更新页面展示评论列表。
③ 分类与标签功能：
- 数据模型：定义分类和标签的数据模型，以及文章与分类、文章与标签之间的关联关系。
- 分类和标签管理：在后台管理界面提供分类和标签的管理功能。
- 文章分类和标签展示：在文章列表页和文章详情页展示文章的分类和标签信息。
- 分类和标签路由：设计分类和标签的路由，例如按分类或标签筛选文章列表。
④ 安全性和后台管理：
- 用户认证与授权：实现后台管理用户的身份验证和授权，保护后台管理功能。
- 输入验证和输出编码：对用户输入进行严格验证，对输出内容进行编码，防止 XSS、 SQL 注入 等安全漏洞。
- 权限控制：实现细粒度的权限控制，例如不同用户角色拥有不同的后台管理权限。
10.3.4 实践总结
使用 Kore Web 框架构建 CMS 系统，可以充分利用 Kore 的高性能和灵活性，构建出轻量级、快速响应的 CMS 应用。在实际开发中，还需要考虑：
- 模板引擎选择：选择合适的 C 语言 模板引擎，例如 mustache.c, handlebars.c 等，提高开发效率。
- 后台管理界面设计：设计用户友好的后台管理界面，提高内容管理效率。
- 主题和插件系统：考虑扩展 CMS 的主题和插件系统，增加 CMS 的可定制性和可扩展性。
- SEO 优化：进行 SEO（Search Engine Optimization，搜索引擎优化），提高博客在搜索引擎中的排名。
- 性能优化：对 CMS 系统进行性能优化，例如缓存页面、优化数据库查询、压缩静态资源等，提高网站访问速度。
Chapter 10 通过三个案例研究，展示了 Kore Web 框架在构建不同类型 Web 应用中的应用。这些案例涵盖了 RESTful API、实时应用和 CMS 系统，展示了 Kore 的高性能、灵活性和易用性，以及在实际项目开发中的价值。希望这些案例能够帮助读者更好地理解和应用 Kore Web 框架。
11. chapter 11： Troubleshooting and Debugging 🐞
11.1 Common Kore Application Issues
在 Kore Web 应用的开发和运行过程中，开发者可能会遇到各种问题。本节将介绍一些常见的 Kore 应用问题及其可能的原因。
11.1.1 Startup Problems
启动问题（Startup Problems）是指 Kore 应用在启动阶段遇到的错误，导致应用无法正常启动或监听端口。
① 端口占用错误：
⚝ 现象：启动 Kore 应用时，控制台输出类似 bind: address already in use 或 EADDRINUSE 的错误信息。
⚝ 原因：指定的监听端口已被其他程序占用。
⚝ 解决方法：
▮▮▮▮ⓐ 检查端口占用情况：使用 netstat -tulnp (Linux) 或 lsof -i :<port> (macOS) 命令查看指定端口是否被占用，以及占用端口的进程 PID。
▮▮▮▮ⓑ 停止占用端口的进程：如果端口被其他非必要的程序占用，可以尝试停止该程序。
▮▮▮▮ⓒ 修改 Kore 监听端口：修改 kore.conf 配置文件中的 server.http.listen 配置项，更换 Kore 应用的监听端口。
② 配置文件错误：
⚝ 现象：启动 Kore 应用时，控制台输出配置文件解析错误信息，例如 config: parse error at line <line_number>。
⚝ 原因：kore.conf 配置文件语法错误，例如配置项格式不正确、值类型错误、缺少必要的配置项等。
⚝ 解决方法：
▮▮▮▮ⓐ 检查配置文件语法：仔细检查 kore.conf 配置文件，根据错误信息定位到错误行，检查语法错误，例如键值对格式、字符串引号、布尔值表示等。
▮▮▮▮ⓑ 参考配置文件示例：参考 Kore 官方文档或示例项目中的 kore.conf 文件，对比检查配置项是否正确。
▮▮▮▮ⓒ 使用配置文件验证工具（如果存在）：部分编辑器或 IDE 可能提供配置文件语法验证功能，可以使用这些工具检查 kore.conf 文件。
③ 依赖库缺失或版本不兼容：
⚝ 现象：启动 Kore 应用时，控制台输出类似 error while loading shared libraries 或 undefined symbol 的错误信息。
⚝ 原因：Kore 应用依赖的动态链接库（例如 libkore.so, libssl.so, libpcre.so 等）缺失，或者版本不兼容。
⚝ 解决方法：
▮▮▮▮ⓐ 检查依赖库安装：确认 Kore 依赖的库（openssl, pcre, zlib）已经正确安装，并且版本符合 Kore 的要求。
▮▮▮▮ⓑ 检查库路径配置：如果依赖库安装在非标准路径下，需要配置系统的动态链接库搜索路径，例如设置 LD_LIBRARY_PATH 环境变量 (Linux)。
▮▮▮▮ⓒ 重新编译 Kore 和应用：尝试重新编译 Kore Web 框架和应用，确保编译链接过程正确。
11.1.2 Request Handling Errors
请求处理错误（Request Handling Errors）是指 Kore 应用在处理客户端 HTTP 请求 时遇到的错误，导致无法正确响应或返回错误状态码。
① 路由未匹配 (404 Not Found)：
⚝ 现象：客户端访问某个 URL 路径时，服务器返回 404 Not Found 错误。
⚝ 原因：请求的 URL 路径在 Kore 应用的路由表中没有匹配的路由规则。
⚝ 解决方法：
▮▮▮▮ⓐ 检查路由配置：检查 kore_main() 函数中的路由配置代码，确认是否定义了请求 URL 路径对应的路由规则。
▮▮▮▮ⓑ 检查 URL 路径拼写：检查客户端请求的 URL 路径拼写是否正确，大小写是否一致（URL 路径通常是大小写敏感的）。
▮▮▮▮ⓒ 检查路由优先级：如果定义了多个路由规则，检查路由优先级是否符合预期，是否存在路由冲突导致路由未被正确匹配。
② 处理器函数错误 (500 Internal Server Error)：
⚝ 现象：客户端请求某个 URL 路径时，服务器返回 500 Internal Server Error 错误。
⚝ 原因：与路由匹配的 处理器函数 在执行过程中发生了错误，例如代码 Bug、异常处理不当、数据库连接失败等。
⚝ 解决方法：
▮▮▮▮ⓐ 查看错误日志：查看 Kore 应用的错误日志文件（errorlog 配置项指定的路径），查找详细的错误信息，例如错误类型、错误堆栈、错误发生位置等。
▮▮▮▮ⓑ 代码调试：使用 调试器（例如 gdb）对 处理器函数 代码进行调试，定位错误发生的位置和原因。
▮▮▮▮ⓒ 完善错误处理：在 处理器函数 中添加完善的错误处理逻辑，捕获可能发生的异常，并返回友好的错误响应，避免直接返回 500 Internal Server Error。
③ 中间件错误：
⚝ 现象：客户端请求某个 URL 路径时，请求处理流程在 中间件 环节中断，可能返回错误状态码或无响应。
⚝ 原因：某个 中间件函数 在执行过程中发生了错误，或者中间件函数返回了 KORE_RESULT_ERROR 导致请求处理流程提前终止。
⚝ 解决方法：
▮▮▮▮ⓐ 查看错误日志：查看 Kore 应用的错误日志文件，查找 中间件 函数执行过程中的错误信息。
▮▮▮▮ⓑ 调试中间件代码：使用 调试器 对 中间件函数 代码进行调试，定位错误发生的位置和原因。
▮▮▮▮ⓒ 检查中间件逻辑：检查 中间件函数 的逻辑是否正确，是否存在 Bug 或异常处理不当的情况。
▮▮▮▮ⓓ 临时禁用中间件：为了排查问题，可以临时禁用某些 中间件，观察问题是否仍然存在，判断是否是某个 中间件 导致的问题。
11.1.3 Database Connection Issues
数据库连接问题（Database Connection Issues）是指 Kore 应用在尝试连接数据库时遇到的错误，导致无法正常访问数据库，影响应用功能。
① 数据库连接配置错误：
⚝ 现象：Kore 应用启动或运行时，无法连接数据库，控制台或日志输出数据库连接错误信息，例如 database: connection failed。
⚝ 原因：kore.conf 配置文件中数据库连接配置信息错误，例如数据库驱动、主机名、端口号、用户名、密码、数据库名称等配置错误。
⚝ 解决方法：
▮▮▮▮ⓐ 检查数据库配置：仔细检查 kore.conf 配置文件中 database 块的配置信息，确认数据库连接配置是否正确，例如主机名、端口号、用户名、密码等是否与数据库服务器配置一致。
▮▮▮▮ⓑ 测试数据库连接：使用数据库客户端工具（例如 psql for PostgreSQL, mysql client for MySQL）尝试使用相同的配置信息连接数据库服务器，验证数据库连接是否正常。
▮▮▮▮ⓒ 检查数据库服务器状态：确认数据库服务器是否正常运行，网络连接是否畅通，数据库服务是否监听在配置的端口上。
② 数据库服务器拒绝连接：
⚝ 现象：Kore 应用尝试连接数据库时，数据库服务器拒绝连接，控制台或日志输出连接被拒绝的错误信息，例如 connection refused。
⚝ 原因：
▮▮▮▮ⓐ 数据库服务器未启动：数据库服务器进程未启动或异常退出。
▮▮▮▮ⓑ 数据库服务器监听地址或端口错误：数据库服务器配置的监听地址或端口与 Kore 应用配置的连接信息不一致。
▮▮▮▮ⓒ 防火墙阻止连接：服务器防火墙阻止了 Kore 应用到数据库服务器的连接请求。
▮▮▮▮ⓓ 数据库访问权限限制：数据库服务器配置了访问权限限制，拒绝了 Kore 应用连接用户的访问。
⚝ 解决方法：
▮▮▮▮ⓐ 检查数据库服务器状态：确认数据库服务器进程是否正在运行，可以使用数据库服务器提供的管理工具或命令行命令检查服务状态。
▮▮▮▮ⓑ 检查数据库服务器配置：检查数据库服务器配置文件，确认监听地址、端口号配置是否正确。
▮▮▮▮ⓒ 配置防火墙规则：配置服务器防火墙规则，允许 Kore 应用服务器到数据库服务器的连接请求通过。
▮▮▮▮ⓓ 检查数据库访问权限：检查数据库服务器的用户权限配置，确认 Kore 应用连接用户是否具有连接数据库和访问所需数据库的权限。
③ 数据库连接超时：
⚝ 现象：Kore 应用尝试连接数据库时，连接超时，控制台或日志输出连接超时错误信息，例如 connection timed out。
⚝ 原因：
▮▮▮▮ⓐ 网络连接问题：Kore 应用服务器到数据库服务器之间的网络连接存在问题，例如网络延迟过高、网络中断等。
▮▮▮▮ⓑ 数据库服务器负载过高：数据库服务器负载过高，无法及时响应连接请求。
▮▮▮▮ⓒ 数据库连接配置超时时间过短：kore.conf 配置文件中数据库连接超时时间配置过短，导致连接还未建立就超时。
▮▮▮▮ⓓ 防火墙或网络设备阻止连接：防火墙或网络设备阻止了 Kore 应用服务器到数据库服务器之间的连接请求。
⚝ 解决方法：
▮▮▮▮ⓐ 检查网络连接：检查 Kore 应用服务器到数据库服务器之间的网络连接是否正常，可以使用 ping 或 traceroute 命令测试网络连通性。
▮▮▮▮ⓑ 检查数据库服务器负载：检查数据库服务器的负载情况，如果负载过高，尝试优化数据库性能或增加服务器资源。
▮▮▮▮ⓒ 调整连接超时时间：适当增加 kore.conf 配置文件中数据库连接超时时间的配置值。
▮▮▮▮ⓓ 检查防火墙和网络设备配置：检查防火墙和网络设备配置，确认是否阻止了 Kore 应用服务器到数据库服务器之间的连接请求。
11.1.4 Performance Bottlenecks
性能瓶颈（Performance Bottlenecks）是指 Kore Web 应用在运行过程中，性能表现不佳，例如响应时间过长、吞吐量较低、资源消耗过高等。
① CPU 密集型操作：
⚝ 现象：Kore 应用 CPU 使用率持续偏高，但响应速度仍然缓慢。
⚝ 原因：处理器函数 或 中间件函数 中存在大量的 CPU 密集型操作（CPU-bound operations），例如复杂的计算、大量的字符串处理、正则表达式匹配等，消耗了大量的 CPU 资源，导致请求处理速度变慢。
⚝ 解决方法：
▮▮▮▮ⓐ 代码优化：优化 CPU 密集型操作 的代码逻辑，例如改进算法、减少计算量、使用更高效的库函数等。
▮▮▮▮ⓑ 异步处理：将 CPU 密集型操作 移到后台线程或进程异步执行，避免阻塞请求处理线程，提高并发处理能力。
▮▮▮▮ⓒ 缓存计算结果：对于计算结果不经常变化的操作，可以使用 缓存 缓存计算结果，减少重复计算。
▮▮▮▮ⓓ 负载均衡：使用 负载均衡 将请求分发到多台服务器，分摊 CPU 负载。
▮▮▮▮ⓔ 硬件升级：升级服务器 CPU 硬件配置，提高 CPU 处理能力。
② I/O 密集型操作：
⚝ 现象：Kore 应用 CPU 使用率不高，但 I/O 等待时间较长，响应速度仍然缓慢。
⚝ 原因：处理器函数 或 中间件函数 中存在大量的 I/O 密集型操作（I/O-bound operations），例如数据库查询、文件读写、网络请求等，I/O 操作的等待时间较长，导致请求处理速度变慢。
⚝ 解决方法：
▮▮▮▮ⓐ 异步 I/O：使用 Kore 提供的异步 API（例如 kore_database_query_async(), http_client_request_async()）进行 I/O 操作，避免阻塞请求处理线程，提高并发处理能力。
▮▮▮▮ⓑ 数据库优化：优化数据库查询性能，例如添加索引、优化查询语句、使用连接池等。
▮▮▮▮ⓒ 缓存数据：对于 frequently accessed data，使用 缓存 缓存数据，减少 I/O 操作 次数。
▮▮▮▮ⓓ 批量 I/O 操作：将多个小的 I/O 操作 合并成批量操作，减少 I/O 调用次数，提高 I/O 效率。
▮▮▮▮ⓔ 使用更快的存储介质：如果 I/O 瓶颈 主要在磁盘 I/O，可以考虑使用 SSD (Solid State Drive) 替代 HDD (Hard Disk Drive)，提高磁盘 I/O 速度。
③ 数据库瓶颈：
⚝ 现象：Kore 应用性能瓶颈主要在数据库访问环节，数据库查询响应时间过长，数据库服务器负载过高。
⚝ 原因：
▮▮▮▮ⓐ 数据库查询语句效率低下：SQL 查询语句没有经过优化，例如缺少索引、全表扫描、 JOIN 操作效率低等。
▮▮▮▮ⓑ 数据库连接数不足：Kore 应用配置的数据库连接数不足，无法满足高并发请求的需求，导致连接等待。
▮▮▮▮ⓒ 数据库服务器硬件资源不足：数据库服务器 CPU、内存、磁盘 I/O 等硬件资源不足，无法支撑高负载请求。
▮▮▮▮ⓓ 数据库表结构设计不合理：数据库表结构设计不合理，例如表字段过多、数据类型选择不当、缺少合适的索引等，影响查询性能。
▮▮▮▮ⓔ 数据库服务器配置不当：数据库服务器配置参数不合理，例如缓存大小、连接数限制、 I/O 参数等配置不当，影响数据库性能。
⚝ 解决方法：
▮▮▮▮ⓐ 数据库性能分析：使用数据库性能分析工具（例如 pgAdmin for PostgreSQL, MySQL Performance Schema for MySQL）分析数据库性能瓶颈，定位性能问题。
▮▮▮▮ⓑ 数据库查询优化：优化 SQL 查询语句，添加索引，避免全表扫描，优化 JOIN 操作，减少不必要的数据返回。
▮▮▮▮ⓒ 增加数据库连接数：适当增加 kore.conf 配置文件中数据库连接池的最大连接数配置项。
▮▮▮▮ⓓ 数据库服务器硬件升级：升级数据库服务器 CPU、内存、磁盘 I/O 等硬件资源，提高数据库服务器处理能力。
▮▮▮▮ⓔ 数据库表结构优化：优化数据库表结构设计，例如字段拆分、表分区、数据归档等，提高查询性能。
▮▮▮▮ⓕ 数据库服务器配置优化：根据数据库服务器硬件资源和负载情况，调整数据库服务器配置参数，优化数据库性能。
11.2 Debugging Tools and Techniques
为了更有效地定位和解决 Kore Web 应用中遇到的问题，开发者可以使用各种 调试工具（Debugging Tools）和 调试技巧（Debugging Techniques）。
11.2.1 Logging and Monitoring
日志记录（Logging）和 监控（Monitoring）是 Web 应用 故障排查（Troubleshooting）和 性能分析（Performance Analysis）的重要手段。
① 日志记录：
Kore Web 框架提供了内置的 日志记录 API (kore_log())，可以将日志信息输出到控制台或日志文件中。在 Kore 应用开发中，应该合理地使用 日志记录，记录关键的运行信息、错误信息、调试信息等。
⚝ 日志级别（Log Level）：Kore 提供了多种日志级别，例如 LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERR, LOG_CRIT 等，可以根据日志信息的严重程度选择合适的日志级别。在开发和调试阶段，可以使用 LOG_DEBUG 或 LOG_INFO 级别输出详细的调试信息；在生产环境，建议使用 LOG_WARNING 或 LOG_ERR 级别，只记录重要的警告和错误信息，减少日志量，提高性能。
⚝ 日志输出目标（Log Output Target）：Kore 可以将日志输出到控制台（标准输出）或日志文件中。在生产环境，通常会将日志输出到日志文件中，方便长期保存和分析。可以使用 kore.conf 配置文件中的 accesslog 和 errorlog 配置项配置访问日志和错误日志的输出路径。
⚝ 日志格式（Log Format）：自定义日志格式，包含时间戳、日志级别、模块名、日志消息等信息，方便日志分析和检索。可以使用 strftime() 函数格式化时间戳，使用字符串拼接或格式化函数构建日志消息。
② 监控：
监控 是指对 Kore Web 应用的运行状态和性能指标进行实时监测，及时发现异常和瓶颈。常用的监控指标包括：
⚝ 应用性能指标：
▮▮▮▮ⓐ 响应时间（Response Time）：请求处理的平均时间、最大时间、 P90、 P99 等分位值。
▮▮▮▮ⓑ 吞吐量（Throughput）：每秒处理的请求数 (Requests Per Second, RPS)。
▮▮▮▮ⓒ 错误率（Error Rate）：请求失败的比例，例如 4xx 错误、 5xx 错误。
▮▮▮▮ⓓ 并发连接数（Concurrent Connections）：当前活跃的连接数。
▮▮▮▮ⓔ WebSocket 连接数：当前活跃的 WebSocket 连接数。
⚝ 服务器资源指标：
▮▮▮▮ⓐ CPU 使用率（CPU Usage）：服务器 CPU 的使用情况。
▮▮▮▮ⓑ 内存使用率（Memory Usage）：服务器内存的使用情况。
▮▮▮▮ⓒ 磁盘 I/O（Disk I/O）：磁盘读写速度、 I/O 等待时间。
▮▮▮▮ⓓ 网络 I/O（Network I/O）：网络带宽使用率、网络延迟、丢包率。
▮▮▮▮ⓔ 数据库连接数：数据库连接池的当前连接数、最大连接数、空闲连接数。
可以使用 系统监控工具（例如 top, htop, vmstat, iostat, netstat）和 APM 系统（Application Performance Monitoring，例如 Prometheus, Grafana, Zabbix, Nagios）进行监控。
11.2.2 Using Debuggers (gdb)
调试器（Debugger）是一种强大的程序调试工具，可以单步执行代码、查看变量值、设置断点、跟踪函数调用堆栈，帮助开发者深入了解程序运行过程，定位 Bug 和错误。
gdb (GNU Debugger) 是 Linux 和 macOS 系统常用的 C 语言 调试器。可以使用 gdb 调试 Kore Web 应用。
① 编译时添加调试信息：
在编译 Kore 应用时，需要添加 -g 编译选项，生成调试信息，以便 gdb 可以加载和使用调试信息。
修改 Makefile，在 CFLAGS 中添加 -g 选项：
1
CFLAGS = -Wall -Wextra -Werror -g -I/usr/local/include # 添加 -g 选项
重新编译 Kore 应用： make
② 使用 gdb 启动 Kore 应用：
使用 gdb 启动 Kore 应用，并设置断点。
1
gdb ./my-kore-app
在 gdb 命令行界面，可以使用以下常用命令：
⚝ break <function_name> 或 b <function_name>：在指定函数入口处设置断点。例如 break hello_handler。
⚝ break <file_name>:<line_number> 或 b <file_name>:<line_number>：在指定文件和行号处设置断点。例如 break src/handlers/hello.c:20。
⚝ run 或 r：运行程序，直到断点或程序结束。
⚝ next 或 n：单步执行下一行代码，不进入函数调用。
⚝ step 或 s：单步执行下一行代码，如果遇到函数调用，则进入函数内部。
⚝ continue 或 c：继续执行程序，直到下一个断点或程序结束。
⚝ print <variable_name> 或 p <variable_name>：打印指定变量的值。例如 p req->path。
⚝ backtrace 或 bt：查看函数调用堆栈。
⚝ frame <frame_number> 或 f <frame_number>：切换到指定堆栈帧。
⚝ quit 或 q：退出 gdb。
示例 gdb 调试流程：
1
gdb ./my-kore-app
2
GNU gdb (GDB) ...
3
...
4
(gdb) break hello_handler # 在 hello_handler 函数入口处设置断点
5
Breakpoint 1 at 0x...: file src/handlers/hello.c, line 5.
6
(gdb) run # 运行程序
7
Starting program: /path/to/my-kore-app
8
[Thread debugging using libthread_db enabled]
9
Using host libthread_db library "/lib64/libthread_db.so.1".
10
[New Thread 0x7ffff7fbb700 (LWP 12345)]
11
... (Kore 应用启动日志) ...
12
Breakpoint 1, hello_handler (req=0x...) at src/handlers/hello.c:5 # 程序运行到断点处暂停
13
5 http_response_header(req, "Content-Type", "text/plain");
14
(gdb) print req->path # 查看 req->path 变量的值
15
$1 = "/hello"
16
(gdb) next # 单步执行下一行代码
17
6 http_response(req, 200, "Hello, Kore!", 12);
18
(gdb) continue # 继续执行程序
19
Continuing.
20
... (程序继续运行，处理请求) ...
21
^C # 按 Ctrl+C 中断程序
22
Program received signal SIGINT, Interrupt.
23
0x00007ffff7a9a6a0 in epoll_wait () from /lib64/libc.so.6
24
(gdb) quit # 退出 gdb
25
A debugging session is active.
26
27
Inferior 1 [process 12345] will be killed.
28
29
Quit anyway? (y or n) y
③ Attach 到正在运行的进程：
如果 Kore 应用已经运行起来，可以使用 gdb attach 到正在运行的进程，进行动态调试。
1
gdb attach
<process_id> 是 Kore 应用进程的 PID (Process ID)。可以使用 ps aux | grep my-kore-app 命令查找 Kore 应用进程的 PID。
11.2.3 Profiling Tools (perf, gprof)
性能分析工具（Profiling Tools）用于分析 Kore Web 应用的性能瓶颈，例如 CPU 占用、 内存分配、 函数调用 耗时等，帮助开发者定位性能优化的重点。
① perf (Performance Counters for Linux)：
perf 是 Linux 系统自带的性能分析工具，基于硬件性能计数器和软件事件，可以收集 CPU 周期、指令数、缓存命中率、 I/O 事件等性能数据，并生成性能分析报告。
使用 perf record 命令收集性能数据：
1
perf record -g ./my-kore-app -f config/kore.conf
-g 选项表示记录函数调用图（Call Graph）。
使用 perf report 命令生成性能分析报告：
1
perf report
perf report 会以交互式界面展示性能分析报告，可以查看 CPU 占用率 高的函数、 热点代码（Hotspot Code）等信息。
② gprof (GNU Profiler)：
gprof 是 GNU 工具链提供的程序性能分析工具，通过在编译和链接阶段添加 Profiling 代码，在程序运行时收集函数调用次数和执行时间，并生成性能分析报告。
编译时添加 -pg 选项：
修改 Makefile，在 CFLAGS 和 LIBS 中添加 -pg 选项：
1
CFLAGS = -Wall -Wextra -Werror -g -pg -I/usr/local/include # 添加 -pg 选项
2
LIBS = -lkore -lssl -lcrypto -lpcre -lz -pg # 添加 -pg 选项
重新编译 Kore 应用： make
运行 Kore 应用，并产生性能数据文件 gmon.out：
1
./my-kore-app -f config/kore.conf
使用 gprof 命令生成性能分析报告：
1
gprof ./my-kore-app gmon.out > profile.report
gprof 会生成文本格式的性能分析报告 profile.report，可以查看函数调用次数、执行时间、函数调用关系图等信息。
11.2.4 Network Analysis Tools (tcpdump, Wireshark)
网络分析工具（Network Analysis Tools）用于捕获和分析 Kore Web 应用的网络通信数据包，例如 TCP 数据包、 HTTP 请求、 HTTP 响应、 WebSocket 帧 等，帮助开发者诊断网络连接问题、协议解析错误、性能瓶颈等。
① tcpdump (TCP DUMP)：
tcpdump 是 Linux 和 macOS 系统常用的命令行网络数据包捕获工具，可以捕获指定网卡、协议、端口的网络数据包，并将数据包内容输出到控制台或保存到文件中。
捕获指定端口（例如 8888 端口）的 TCP 数据包：
1
sudo tcpdump -i tcp port 8888 -vv -X -s 0
<network_interface> 是网卡名称，例如 eth0, en0。 -vv 选项表示输出更详细的信息， -X 选项表示以十六进制和 ASCII 码显示数据包内容， -s 0 选项表示捕获完整的数据包。
② Wireshark (前身 Ethereal)：
Wireshark 是一个图形化的网络协议分析器，功能强大，界面友好，可以捕获和分析各种网络协议的数据包，包括 HTTP, TCP, UDP, DNS, SSL/TLS, WebSocket 等。
使用 Wireshark 捕获和分析 Kore Web 应用的网络数据包，可以：
⚝ 查看 HTTP 请求和响应报文：分析 HTTP 请求方法、 URL 路径、 HTTP 头部、 请求体、 响应状态码、 响应头部、 响应体 等信息，诊断 HTTP 协议 错误、 API 调用问题。
⚝ 分析 WebSocket 通信：查看 WebSocket 握手过程、 WebSocket 帧 类型、 WebSocket 消息 内容，诊断 WebSocket 连接 问题、消息传输错误。
⚝ 分析 TCP 连接：查看 TCP 三次握手、 TCP 连接状态、 TCP 重传、 TCP 窗口大小 等信息，诊断网络连接问题、 TCP 性能 问题。
⚝ 分析 SSL/TLS 加密通信：如果 Kore 应用启用了 HTTPS，可以使用 Wireshark 解密 SSL/TLS 加密的数据包（需要提供服务器私钥），分析加密通信内容。
11.3 Troubleshooting Workflow
一个有效的 故障排查流程（Troubleshooting Workflow）可以帮助开发者系统地、高效地定位和解决 Kore Web 应用中遇到的问题。
11.3.1 Reproducing the Issue
重现问题（Reproducing the Issue）是 故障排查 的第一步。只有能够稳定地重现问题，才能进行后续的分析和调试。
① 记录问题发生时的环境信息：
记录问题发生时的环境信息，例如：
⚝ 操作系统：操作系统类型和版本。
⚝ Kore 版本：Kore Web 框架的版本号。
⚝ 依赖库版本：依赖库（例如 openssl, pcre, zlib）的版本号。
⚝ 配置文件：kore.conf 配置文件内容。
⚝ 客户端信息：客户端浏览器类型和版本、客户端 IP 地址。
⚝ 网络环境：网络拓扑结构、网络连接方式。
⚝ 负载情况：服务器负载情况、并发用户数、请求频率。
② 详细描述问题现象：
详细描述问题现象，例如：
⚝ 错误类型：错误状态码、错误信息、异常类型。
⚝ 发生频率：问题是偶发还是必现。
⚝ 发生场景：问题在哪些场景下发生，例如特定 URL 路径、特定操作步骤、特定用户输入。
⚝ 影响范围：问题影响的功能范围、用户影响程度。
③ 编写可重现问题的步骤：
编写详细的步骤，描述如何重现问题。步骤应该尽可能详细和可操作，包括：
⚝ 前置条件：重现问题需要满足的前置条件，例如用户登录状态、数据库数据状态。
⚝ 操作步骤：重现问题的具体操作步骤，例如访问的 URL 路径、提交的表单数据、点击的按钮。
⚝ 预期结果：预期应该得到的结果。
⚝ 实际结果：实际得到的结果，与预期结果的差异。
11.3.2 Isolating the Problem
隔离问题（Isolating the Problem）是指将问题范围缩小到最小的范围，例如特定模块、特定函数、特定代码行，方便后续的深入分析和调试。
① 分层排查：
按照应用架构层次，逐层排查问题。例如：
⚝ 网络层：检查网络连接是否正常、网络延迟是否过高、网络设备是否工作正常。
⚝ HTTP 层：检查 HTTP 请求 和 响应 报文是否符合协议规范、 HTTP 状态码 是否正确、 HTTP 头部 是否完整。
⚝ Kore 框架层：检查路由配置是否正确、 中间件 执行是否正常、 处理器 函数是否被正确调用。
⚝ 业务逻辑层：检查业务逻辑代码是否存在 Bug、算法是否正确、数据处理是否正确。
⚝ 数据访问层：检查数据库连接是否正常、 SQL 查询语句是否正确、数据库操作是否成功。
⚝ 数据库层：检查数据库服务器是否正常运行、数据库配置是否正确、数据库表结构是否合理。
② 模块化排查：
将 Kore 应用划分为多个模块，逐个模块排查问题。例如：
⚝ 路由模块：检查路由配置是否正确，路由规则是否匹配。
⚝ 中间件模块：逐个禁用 中间件，排查是否是某个 中间件 导致的问题。
⚝ 处理器模块：针对特定的 处理器函数 进行排查，例如代码逻辑、数据处理、错误处理。
⚝ 数据模型模块：检查数据模型定义是否正确、数据结构是否合理。
⚝ 数据访问层模块：排查数据库操作代码，例如 SQL 查询语句、数据库连接、事务处理。
⚝ 外部依赖模块：如果应用依赖外部服务或 API，排查外部依赖是否正常。
③ 简化问题场景：
尝试简化问题场景，例如：
⚝ 简化请求参数：减少请求参数的数量，简化请求体数据，观察问题是否仍然存在。
⚝ 简化路由规则：临时修改路由规则，只保留最简单的路由，排查是否是路由配置导致的问题。
⚝ 禁用部分功能：临时禁用部分功能模块，例如评论功能、缓存功能，排查是否是某个功能模块导致的问题。
11.3.3 Analyzing Logs and Metrics
分析日志和指标（Analyzing Logs and Metrics）是 故障排查 的关键步骤。通过分析 Kore Web 应用的日志和监控指标，可以获取问题发生时的详细信息，定位问题根源。
① 分析错误日志：
查看 Kore 应用的错误日志文件（errorlog 配置项指定的路径），查找错误信息，例如：
⚝ 错误类型：错误日志中会记录错误类型，例如 ERROR, WARNING, CRITICAL。
⚝ 错误消息：错误日志中会包含详细的错误消息，描述错误发生的原因和位置。
⚝ 时间戳：错误日志中会记录错误发生的时间戳，可以根据时间戳关联其他日志和监控数据。
⚝ 模块名：错误日志中可能会记录错误发生的模块名或函数名，帮助定位错误代码位置。
⚝ 堆栈信息：部分错误日志会包含堆栈信息（Stack Trace），显示函数调用堆栈，帮助定位错误调用链。
② 分析访问日志：
查看 Kore 应用的访问日志文件（accesslog 配置项指定的路径），分析请求访问情况，例如：
⚝ 请求 URL：分析请求的 URL 路径，定位问题请求。
⚝ 请求方法：分析请求方法（GET, POST, PUT, DELETE），定位问题请求类型。
⚝ 客户端 IP 地址：分析客户端 IP 地址，定位问题客户端。
⚝ 响应状态码：分析响应状态码，例如 4xx 错误、 5xx 错误，判断请求是否成功。
⚝ 响应时间：分析响应时间，判断请求处理性能是否正常，是否存在性能瓶颈。
⚝ User-Agent：分析客户端 User-Agent 头部，判断客户端类型和版本。
③ 分析监控指标：
查看 Kore 应用的监控指标数据，分析性能瓶颈和资源消耗情况，例如：
⚝ 响应时间：分析响应时间曲线，判断是否存在响应时间异常升高的情况。
⚝ 吞吐量：分析吞吐量曲线，判断吞吐量是否达到预期水平，是否存在吞吐量下降的情况。
⚝ 错误率：分析错误率曲线，判断错误率是否异常升高，是否存在大量请求失败的情况。
⚝ CPU 使用率：分析 CPU 使用率曲线，判断 CPU 是否成为性能瓶颈，是否存在 CPU 占用率过高的情况。
⚝ 内存使用率：分析内存使用率曲线，判断内存使用是否合理，是否存在内存泄漏或内存溢出风险。
⚝ 数据库连接数：分析数据库连接数曲线，判断数据库连接数是否达到上限，是否存在数据库连接瓶颈。
11.3.4 Step-by-Step Debugging
单步调试（Step-by-Step Debugging）是指使用 调试器（例如 gdb）单步执行 Kore 应用代码，逐行查看代码执行过程，观察变量值变化，深入分析代码逻辑，定位 Bug 和错误。
① 设置断点：
在可能发生错误的代码行或函数入口处设置断点，例如：
⚝ 异常处理代码：在异常处理分支代码处设置断点，例如 if (error) 语句、 catch 语句。
⚝ 关键函数入口：在关键函数入口处设置断点，例如 处理器函数、 中间件函数、数据访问函数。
⚝ 循环或条件语句：在循环语句或条件语句内部设置断点，观察循环执行过程或条件判断结果。
⚝ 可疑代码行：在怀疑可能存在 Bug 的代码行设置断点。
② 单步执行：
使用调试器的单步执行命令（例如 next, step）逐行执行代码，观察代码执行流程。
③ 查看变量值：
在单步执行过程中，使用调试器的查看变量值命令（例如 print, watch）查看关键变量的值，例如请求对象、响应对象、函数参数、局部变量。
④ 分析调用堆栈：
使用调试器的查看调用堆栈命令（例如 backtrace）查看函数调用堆栈，了解函数调用关系和执行路径。
⑤ 条件断点：
使用调试器的条件断点功能，只在满足特定条件时触发断点，例如变量值满足特定条件、循环执行到特定次数。
11.3.5 Seeking Community Support
当遇到难以解决的 Kore Web 应用问题时，可以寻求 社区支持（Community Support），例如：
① 查阅官方文档：
Kore Web 框架官方文档提供了详细的框架介绍、 API 参考、 配置说明、 示例代码 等信息，可以查阅官方文档，查找问题的答案或解决方案。
② 搜索社区论坛和问答平台：
搜索 Kore Web 框架的社区论坛、 Stack Overflow 等问答平台，查找是否有其他开发者遇到过类似的问题，并参考已有的解决方案。
③ 向社区提问：
如果搜索不到相关信息，可以在 Kore Web 框架的社区论坛或问答平台提问，详细描述问题现象、环境信息、代码示例、已尝试的解决方法等，寻求社区的帮助。提问时，应尽量提供足够的信息，方便社区成员理解问题并提供有效的帮助。
④ 查看源代码：
Kore Web 框架是开源的，可以查看 Kore 的源代码，深入了解框架的实现原理，查找 Bug 或错误。
⑤ 提交 Bug 报告：
如果确认问题是 Kore 框架自身的 Bug，可以在 Kore 的 GitHub 仓库（GitHub Repository）提交 Bug 报告，向 Kore 开发团队反馈 Bug 信息，并期待官方修复。
Chapter 11 详细介绍了 Kore Web 应用的 故障排查和调试 方法，包括常见的应用问题、调试工具和技巧、以及故障排查流程。掌握这些内容可以帮助开发者更有效地诊断和解决 Kore Web 应用中遇到的问题，提高开发效率和应用质量。
12. chapter 12： 总结与展望 (Conclusion and Future Outlook) 🌅
12.1 本书总结 (Summary of the Book) 📝
本书《Kore Web 框架权威指南》系统性地介绍了 Kore Web 框架的各个方面，旨在为读者提供一份全面、深入、实用的 Kore Web 开发指南。从框架的 简介（Introduction）和 核心概念（Core Concepts），到 API 详解（API Details）、 开发实践（Development Practices）、 安全性（Security）、 测试与部署（Testing and Deployment），再到 高级主题（Advanced Topics）和 案例研究（Case Studies），本书力求覆盖 Kore Web 框架的方方面面，帮助读者从入门到精通。
① 框架概览与核心理念：
本书首先从 chapter 1 和 chapter 2 入手，介绍了 Kore Web 框架的 起源、 设计哲学、 核心特性 和 适用场景。强调了 Kore 作为一款基于 C 语言 开发的 高性能、 安全、 灵活 的 Web 框架的独特优势，并深入讲解了 请求处理流程、 路由、 中间件、 配置管理 等核心概念，为后续章节的学习奠定了基础。
② API 详解与功能模块：
chapter 3， chapter 4 和 chapter 5 详细解读了 Kore Web 框架的核心 API，涵盖了 HTTP 处理、 数据处理与存储、 异步与并发 等关键功能模块。通过丰富的代码示例和场景分析，帮助读者理解和掌握 Kore 提供的各种 API，例如 请求对象、 响应对象、 会话管理、 Cookie 处理、 数据库集成、 缓存机制、 WebSocket 支持、 事件驱动编程 等。
③ 开发实践与最佳实践：
chapter 6， chapter 7 和 chapter 8 侧重于 Kore Web 应用的 开发实践 和 最佳实践。讨论了 项目结构与组织、 模板引擎集成、 表单处理与验证、 身份验证与授权、 安全性加固、 单元测试、 集成测试、 性能测试 以及 生产环境部署 等关键环节，旨在帮助读者构建高质量、可维护、安全、可靠的 Kore Web 应用。
④ 高级主题与扩展应用：
chapter 9 和 chapter 10 深入探讨了 Kore Web 框架的 高级主题 和 扩展应用。介绍了 自定义中间件、 C 扩展模块开发、 性能优化策略、 与其他技术的集成 等高级特性，并结合 RESTful API、 实时应用、 CMS 系统 等 案例研究，展示了 Kore Web 框架在不同应用场景下的强大能力和灵活应用。
⑤ 问题排查与调试技巧：
chapter 11 专门讲解了 Kore Web 应用的 问题排查与调试 方法，总结了常见的 应用问题、 调试工具 和 调试技巧，并提供了一套实用的 故障排查流程，帮助读者快速定位和解决开发和运行过程中遇到的各种问题。
通过本书的学习，读者应该能够全面掌握 Kore Web 框架的核心知识和实战技能，并能够运用 Kore Web 框架构建各种类型的 Web 应用，从简单的 API 服务 到复杂的 实时应用 和 CMS 系统。
12.2 Kore Web 框架的优势与局限性 (Strengths and Limitations) 💪 😞
Kore Web 框架作为一款独特的 C 语言 Web 框架，拥有诸多优势，但也存在一些局限性。理解其 优势与局限性，有助于开发者更好地选择和使用 Kore Web 框架。
12.2.1 优势 (Strengths) 💪
① 卓越的性能 (Exceptional Performance)：
基于 C 语言 开发，编译型语言的优势，底层控制能力强，性能卓越，尤其在处理 高并发 和 低延迟 请求时表现突出。 异步非阻塞 I/O 模型和 多进程架构 进一步提升了 Kore 的并发处理能力。
② 安全性 (Security Focused)：
代码库精简，降低安全漏洞风险。 内存安全 意识强，注重避免常见的 C 语言 内存错误。内置 HTTPS 支持 和 会话管理安全特性。鼓励安全编码实践，有助于构建更安全的 Web 应用。
③ 灵活性与可扩展性 (Flexibility and Extensibility)：
模块化设计，核心功能与扩展功能分离，方便开发者按需选择和扩展功能。支持 自定义中间件 和 C 扩展模块，提供了强大的扩展能力。 底层控制 能力强，方便开发者进行精细的性能调优和资源控制。
④ 轻量级与高效 (Lightweight and Efficient)：
代码库精简，资源消耗低，启动速度快，运行效率高。 适用于资源受限的环境，例如 嵌入式系统 和 物联网 (IoT) 设备。
⑤ 简洁的 API 与易用性 (Simple API and Ease of Use)：
提供清晰、简洁、文档完善的 API，上手容易，开发效率高。 避免了过度抽象和复杂性，让开发者专注于业务逻辑实现。
12.2.2 局限性 (Limitations) 😞
① C 语言的学习曲线 (C Language Learning Curve)：
使用 C 语言 开发，相对于 Python, JavaScript, PHP 等 解释型语言， C 语言 的学习曲线较陡峭，需要开发者具备扎实的 C 语言 基础和内存管理知识。
② 生态系统相对较小 (Smaller Ecosystem)：
与成熟的 Python, JavaScript Web 框架相比，Kore 的 生态系统 相对较小，第三方库和社区资源相对较少。 开发者可能需要自行实现部分常用功能或集成第三方 C 库。
③ 开发效率与迭代速度 (Development Speed and Iteration)：
相对于 动态语言 框架， C 语言 开发的 Web 应用，在开发效率和迭代速度方面可能略有不足。 编译、链接、部署过程相对复杂，代码修改后需要重新编译。
④ 错误处理与调试难度 (Error Handling and Debugging)：
C 语言 的错误处理机制相对原始，错误信息可能不够友好。 C 语言 内存错误（例如段错误、内存泄漏）的调试难度较高，需要熟练掌握 调试工具 和技巧。
⑤ 适用场景相对受限 (Limited Application Scenarios)：
Kore Web 框架更适合构建 高性能、 安全、 资源敏感型 的 Web 应用，例如 API 网关、 实时通信服务、 边缘计算 应用、 嵌入式系统 Web 服务等。 对于对开发效率要求更高、业务逻辑更复杂、生态系统依赖更强的 企业级 Web 应用，可能需要综合考虑选择更成熟的框架。
12.3 未来展望 (Future Outlook) 🔮
Kore Web 框架虽然目前相对小众，但凭借其独特的优势和不断发展的社区，未来仍然具有广阔的发展前景。
① 持续优化性能与安全性 (Continuous Performance and Security Improvement)：
Kore 社区将持续致力于优化框架的 性能 和 安全性，例如进一步提升 I/O 效率、优化内存管理、增强安全特性、修复已知漏洞等，保持 Kore 在 高性能 和 安全 Web 框架领域的领先地位。
② 扩展功能模块与生态系统 (Expanding Functionality and Ecosystem)：
Kore 社区将积极扩展框架的功能模块，例如完善 ORM 支持、增强 WebSocket 功能、提供更多常用的 中间件 组件、改进 开发工具 和 文档 等，逐步完善 Kore 的 生态系统，降低开发门槛，提高开发效率。
③ 适应新的技术趋势 (Adapting to New Technology Trends)：
Kore 社区将密切关注 Web 开发 领域的新技术趋势，例如 HTTP/3, WebAssembly, Serverless, 边缘计算 等，并考虑将这些新技术融入到 Kore Web 框架中，保持 Kore 的技术先进性和竞争力。
④ 社区发展与用户增长 (Community Growth and User Adoption)：
Kore 社区将积极扩大社区规模，吸引更多开发者参与到 Kore 的开发和推广中来，共同建设和完善 Kore Web 框架。随着 Kore 的功能不断完善、生态系统逐步壮大，相信会有越来越多的开发者选择 Kore Web 框架，Kore 的用户群体也将持续增长。
⑤ 在特定领域发挥更大价值 (Unlocking Greater Value in Specific Domains)：
Kore Web 框架在 高性能 API 服务、 实时应用、 嵌入式系统、 边缘计算 等领域具有独特的优势和应用价值。未来，Kore 将在这些特定领域发挥更大的作用，为构建 下一代互联网基础设施 和 智能设备 提供强有力的技术支撑。
总而言之，Kore Web 框架虽然不是万能的，但其 高性能、 安全、 灵活 的特性，使其在特定的应用场景下具有不可替代的价值。随着 Kore 社区的不断发展和壮大，相信 Kore Web 框架的未来将更加光明，为 Web 开发领域带来更多惊喜。
本书到此就告一段落了，希望本书能够帮助读者深入理解和掌握 Kore Web 框架，并在实际项目中成功应用 Kore，构建出高性能、高可靠的 Web 应用。 感谢您的阅读！ 🙏
附录 A： Kore API 参考 📚
本附录提供 Kore Web 框架常用 API 的参考，方便开发者快速查阅。
A.1 HTTP API 参考 🌐
A.1.1 请求对象 (Request Object) API
A.1.1.1 struct http_request *
表示 HTTP 请求 对象的结构体。
A.1.1.2 int http_request_is_websocket(struct http_request *req)
检查请求是否为 WebSocket 升级请求。
1
int http_request_is_websocket(struct http_request *req);
- 参数：
req：要检查的struct http_request *对象。
- 返回值：
1：如果请求是 WebSocket 升级请求。0：否则。
A.1.1.3 const char *http_request_method_str(struct http_request *req)
获取 HTTP 请求方法 的字符串表示形式。
1
const char *http_request_method_str(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- HTTP 请求方法 的字符串，例如
"GET","POST"等。
- HTTP 请求方法 的字符串，例如
A.1.1.4 const char *http_request_path(struct http_request *req)
获取请求路径（Path）。
1
const char *http_request_path(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 请求路径的字符串。
A.1.1.5 const char *http_request_query_string(struct http_request *req)
获取查询字符串（Query String）。
1
const char *http_request_query_string(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 查询字符串，例如
"param1=value1¶m2=value2"，如果没有查询字符串则返回NULL。
- 查询字符串，例如
A.1.1.6 const char *http_request_query_parameter(struct http_request *req, const char *name)
根据参数名获取查询参数值。
1
const char *http_request_query_parameter(struct http_request *req, const char *name);
- 参数：
req：struct http_request *对象。name：参数名字符串。
- 返回值：
- 参数值字符串，如果参数不存在则返回
NULL。
- 参数值字符串，如果参数不存在则返回
A.1.1.7 const char *http_request_path_parameter(struct http_request *req, const char *name)
根据参数名获取路径参数值（动态路由参数）。
1
const char *http_request_path_parameter(struct http_request *req, const char *name);
- 参数：
req：struct http_request *对象。name：参数名字符串，与路由定义中的占位符名称一致。
- 返回值：
- 参数值字符串，如果参数不存在则返回
NULL。
- 参数值字符串，如果参数不存在则返回
A.1.1.8 const char *http_request_header(struct http_request *req, const char *name)
根据头部名称获取请求头的值。
1
const char *http_request_header(struct http_request *req, const char *name);
- 参数：
req：struct http_request *对象。name：头部名称字符串。
- 返回值：
- 头部值字符串，如果头部不存在则返回
NULL。
- 头部值字符串，如果头部不存在则返回
A.1.1.9 void *http_request_body_raw(struct http_request *req, size_t *len)
获取原始请求体数据。
1
void *http_request_body_raw(struct http_request *req, size_t *len);
- 参数：
req：struct http_request *对象。len：输出参数，用于接收请求体数据长度。
- 返回值：
- 指向请求体数据的指针，如果没有请求体则返回
NULL。
- 指向请求体数据的指针，如果没有请求体则返回
A.1.1.10 struct json_value *http_request_body_json(struct http_request *req)
将请求体解析为 JSON 对象。
1
struct json_value *http_request_body_json(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 指向解析后的
struct json_value *对象，如果解析失败或请求体为空则返回NULL。
- 指向解析后的
A.1.1.11 struct form_data *http_request_body_form(struct http_request *req)
将请求体解析为表单数据对象。
1
struct form_data *http_request_body_form(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 指向解析后的
struct form_data *对象，如果解析失败或请求体为空则返回NULL。
- 指向解析后的
A.1.1.12 const char *http_request_cookie(struct http_request *req, const char *name)
根据 Cookie 名称获取 Cookie 值。
1
const char *http_request_cookie(struct http_request *req, const char *name);
- 参数：
req：struct http_request *对象。name： Cookie 名称字符串。
- 返回值：
- Cookie 值字符串，如果 Cookie 不存在则返回
NULL。
- Cookie 值字符串，如果 Cookie 不存在则返回
A.1.2 响应对象 (Response Object) API
A.1.2.1 void http_response_status(struct http_request *req, int status_code)
设置 HTTP 响应状态码。
1
void http_response_status(struct http_request *req, int status_code);
- 参数：
req：struct http_request *对象。status_code： HTTP 状态码，例如200,404,500等。
A.1.2.2 void http_response_header(struct http_request *req, const char *name, const char *value)
设置 HTTP 响应头。
1
void http_response_header(struct http_request *req, const char *name, const char *value);
- 参数：
req：struct http_request *对象。name：头部名称字符串。value：头部值字符串。
A.1.2.3 void http_response(struct http_request *req, int status_code, const void *body, size_t length)
发送 HTTP 响应，设置状态码和响应体。
1
void http_response(struct http_request *req, int status_code, const void *body, size_t length);
- 参数：
req：struct http_request *对象。status_code： HTTP 状态码。body：指向响应体数据的指针。length：响应体数据长度。
A.1.2.4 void http_response_stream(struct http_request *req, const void *body_part, size_t length)
流式发送 HTTP 响应体 数据。
1
void http_response_stream(struct http_request *req, const void *body_part, size_t length);
- 参数：
req：struct http_request *对象。body_part：指向响应体数据块的指针。length：响应体数据块长度。
A.1.2.5 void http_response_open(struct http_request *req, int status_code, const char *content_type)
开始流式 HTTP 响应，设置状态码和 Content-Type 头部。
1
void http_response_open(struct http_request *req, int status_code, const char *content_type);
- 参数：
req：struct http_request *对象。status_code： HTTP 状态码。content_type： Content-Type 头部值，例如"text/plain","application/json"。
A.1.2.6 void http_response_close(struct http_request *req)
结束流式 HTTP 响应。
1
void http_response_close(struct http_request *req);
- 参数：
req：struct http_request *对象。
A.1.2.7 void http_response_json(struct http_request *req, int status_code, struct json_value *json_value)
发送 JSON 响应，设置状态码和 Content-Type: application/json 头部。
1
void http_response_json(struct http_request *req, int status_code, struct json_value *json_value);
- 参数：
req：struct http_request *对象。status_code： HTTP 状态码。json_value：指向struct json_value *对象的指针，表示要发送的 JSON 数据。
A.1.2.8 void http_response_redirect(struct http_request *req, int status_code, const char *url)
发送 HTTP 重定向 响应。
1
void http_response_redirect(struct http_request *req, int status_code, const char *url);
- 参数：
req：struct http_request *对象。status_code： HTTP 重定向状态码，例如302,301。url：重定向 URL。
A.1.2.9 void http_response_error(struct http_request *req, int status_code)
发送 HTTP 错误 响应，使用默认错误页面。
1
void http_response_error(struct http_request *req, int status_code);
- 参数：
req：struct http_request *对象。status_code： HTTP 错误状态码，例如404,500。
A.1.2.10 void http_response_cookie_set(struct http_request *req, const char *name, const char *value, const struct http_cookie_options *options)
设置 Cookie。
1
void http_response_cookie_set(struct http_request *req, const char *name, const char *value, const struct http_cookie_options *options);
- 参数：
req：struct http_request *对象。name： Cookie 名称字符串。value： Cookie 值字符串。options：指向struct http_cookie_options *对象的指针，用于配置 Cookie 选项，可以为NULL使用默认选项。
A.1.3 会话 (Session) API
A.1.3.1 struct http_session *http_session_create(struct http_request *req)
创建或获取 会话 对象。
1
struct http_session *http_session_create(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 指向
struct http_session *对象的指针，表示 会话 对象。
- 指向
A.1.3.2 struct http_session *http_session_get(struct http_request *req)
获取当前请求的 会话 对象，如果会话不存在则返回 NULL。
1
struct http_session *http_session_get(struct http_request *req);
- 参数：
req：struct http_request *对象。
- 返回值：
- 指向
struct http_session *对象的指针，表示 会话 对象，如果会话不存在则返回NULL。
- 指向
A.1.3.3 void http_session_set_string(struct http_session *session, const char *key, const char *value)
设置 会话数据 (字符串值)。
1
void http_session_set_string(struct http_session *session, const char *key, const char *value);
- 参数：
session：struct http_session *对象。key：会话数据键名字符串。value：会话数据值字符串。
A.1.3.4 const char *http_session_get_string(struct http_session *session, const char *key)
获取 会话数据 (字符串值)。
1
const char *http_session_get_string(struct http_session *session, const char *key);
- 参数：
session：struct http_session *对象。key：会话数据键名字符串。
- 返回值：
- 会话数据值字符串，如果键名不存在则返回
NULL。
- 会话数据值字符串，如果键名不存在则返回
A.1.3.5 void http_session_destroy(struct http_request *req, struct http_session *session)
销毁 会话。
1
void http_session_destroy(struct http_request *req, struct http_session *session);
- 参数：
req：struct http_request *对象。session：struct http_session *对象。
A.1.4 HTTP 客户端 (HTTP Client) API
A.1.4.1 struct http_client *http_client_alloc(void)
分配 HTTP 客户端 对象。
1
struct http_client *http_client_alloc(void);
- 参数：
- 无
- 返回值：
- 指向新分配的
struct http_client *对象的指针。
- 指向新分配的
A.1.4.2 void http_client_free(struct http_client *client)
释放 HTTP 客户端 对象。
1
void http_client_free(struct http_client *client);
- 参数：
client：要释放的struct http_client *对象。
A.1.4.3 void http_client_set_url(struct http_client *client, const char *url)
设置 HTTP 客户端 请求 URL。
1
void http_client_set_url(struct http_client *client, const char *url);
- 参数：
client：struct http_client *对象。url：请求 URL 字符串。
A.1.4.4 int http_client_request_async(struct http_client *client, struct http_request *req, void (*callback)(struct http_client *, void *), void *arg, int timeout)
发起 异步 HTTP 客户端请求。
1
int http_client_request_async(struct http_client *client, struct http_request *req, void (*callback)(struct http_client *, void *), void *arg, int timeout);
- 参数：
client：struct http_client *对象。req：struct http_request *对象，表示要发送的请求。callback：回调函数，请求完成时调用。arg：用户自定义参数，传递给回调函数。timeout：请求超时时间，单位毫秒。
- 返回值：
KORE_RESULT_OK：请求发起成功。KORE_RESULT_ERROR：请求发起失败。
A.2 数据库 API 参考 🗄️
A.2.1 struct kore_database *kore_database_get(const char *name)
根据数据库配置名称获取数据库连接对象。
1
struct kore_database *kore_database_get(const char *name);
- 参数：
name：kore.conf中配置的数据库名称字符串。
- 返回值：
- 指向
struct kore_database *对象的指针，表示数据库连接对象，如果配置不存在则返回NULL。
- 指向
A.2.2 struct kore_db_result *kore_database_query(struct kore_database *db, const char *query, ...)
执行 SQL 查询，并返回查询结果对象。
1
struct kore_db_result *kore_database_query(struct kore_database *db, const char *query, ...);
- 参数：
db：struct kore_database *对象。query： SQL 查询语句，可以使用参数占位符$1,$2, ...。...：可变参数列表，用于传递 SQL 查询参数值。
- 返回值：
- 指向
struct kore_db_result *对象的指针，表示查询结果对象，如果查询失败则返回NULL。
- 指向
A.2.3 int kore_database_query_async(struct kore_database *db, const char *query, void (*callback)(struct kore_database *, void *, struct kore_db_result *), void *arg, ...)
异步 执行 SQL 查询。
1
int kore_database_query_async(struct kore_database *db, const char *query, void (*callback)(struct kore_database *, void *, struct kore_db_result *), void *arg, ...);
- 参数：
db：struct kore_database *对象。query： SQL 查询语句。callback：回调函数，查询完成时调用。arg：用户自定义参数，传递给回调函数。...：可变参数列表，用于传递 SQL 查询参数值。
- 返回值：
KORE_RESULT_OK：异步查询发起成功。KORE_RESULT_ERROR：异步查询发起失败。
A.2.4 kore_database_result_next_row(struct kore_db_result *result)
移动到查询结果集的下一行。
1
kore_database_result_next_row(struct kore_db_result *result);
- 参数：
result：struct kore_db_result *对象。
- 返回值：
1：如果成功移动到下一行。0：如果已到达结果集末尾。
A.2.5 const char *kore_database_result_get_string(struct kore_db_result *result, int column_index)
获取当前行指定列的字符串值。
1
const char *kore_database_result_get_string(struct kore_db_result *result, int column_index);
- 参数：
result：struct kore_db_result *对象。column_index：列索引，从0开始。
- 返回值：
- 列值字符串。
A.2.6 int kore_database_result_get_integer(struct kore_db_result *result, int column_index)
获取当前行指定列的整数值。
1
int kore_database_result_get_integer(struct kore_db_result *result, int column_index);
- 参数：
result：struct kore_db_result *对象。column_index：列索引，从0开始。
- 返回值：
- 列值整数。
A.2.7 void kore_database_result_free(struct kore_db_result *result)
释放查询结果对象。
1
void kore_database_result_free(struct kore_db_result *result);
- 参数：
result：struct kore_db_result *对象。
A.3 WebSocket API 参考 💬
A.3.1 void kore_websocket_handler_add(const char *path, int (*handler)(struct http_request *))
添加 WebSocket 路由处理器。
1
void kore_websocket_handler_add(const char *path, int (*handler)(struct http_request *));
- 参数：
path： WebSocket 连接路径字符串。handler： WebSocket 处理器函数指针。
A.3.2 int http_websocket_handshake(struct http_request *req, const char *protocol)
执行 WebSocket 握手。
1
int http_websocket_handshake(struct http_request *req, const char *protocol);
- 参数：
req：struct http_request *对象。protocol：可选的 WebSocket 子协议字符串，可以为NULL。
- 返回值：
KORE_RESULT_OK：握手成功。KORE_RESULT_ERROR：握手失败。
A.3.3 void websocket_send_message(struct websocket *ws, uint8_t op, void *data, size_t len)
发送 WebSocket 消息。
1
void websocket_send_message(struct websocket *ws, uint8_t op, void *data, size_t len);
- 参数：
ws：struct websocket *对象。op： WebSocket 操作码，例如WEBSOCKET_OP_TEXT,WEBSOCKET_OP_BINARY。data：指向消息数据的指针。len：消息数据长度。
A.3.4 void websocket_close(struct websocket *ws)
关闭 WebSocket 连接。
1
void websocket_close(struct websocket *ws);
- 参数：
ws：struct websocket *对象。
A.3.5 void websocket_set_message_callback(struct websocket *ws, int (*cb)(struct websocket *, uint8_t, void *, size_t))
设置 WebSocket 消息接收回调函数。
1
void websocket_set_message_callback(struct websocket *ws, int (*cb)(struct websocket *, uint8_t, void *, size_t));
- 参数：
ws：struct websocket *对象。cb：消息接收回调函数指针。
A.3.6 void websocket_set_close_callback(struct websocket *ws, void (*cb)(struct websocket *))
设置 WebSocket 连接关闭回调函数。
1
void websocket_set_close_callback(struct websocket *ws, void (*cb)(struct websocket *));
- 参数：
ws：struct websocket *对象。cb：连接关闭回调函数指针。
A.4 定时器 (Timer) API 参考 ⏰
A.4.1 int kore_timer_add(void (*callback)(void *), void *arg, int timeout, int repeat)
添加定时器。
1
int kore_timer_add(void (*callback)(void *), void *arg, int timeout, int repeat);
- 参数：
callback：定时器回调函数指针。arg：用户自定义参数，传递给回调函数。timeout：定时器延迟时间，单位毫秒。repeat：定时器类型，KORE_TIMER_ONESHOT(单次触发) 或KORE_TIMER_REPEAT(重复触发)。
- 返回值：
KORE_RESULT_OK：定时器添加成功。KORE_RESULT_ERROR：定时器添加失败。
A.4.2 void kore_timer_remove(void (*callback)(void *), void *arg)
移除定时器。
1
void kore_timer_remove(void (*callback)(void *), void *arg);
- 参数：
callback：要移除的定时器的回调函数指针。arg：与回调函数关联的用户自定义参数。
A.5 日志 (Log) API 参考 📝
A.5.1 void kore_log(int level, const char *fmt, ...)
输出日志信息。
1
void kore_log(int level, const char *fmt, ...);
- 参数：
level：日志级别，例如LOG_DEBUG,LOG_INFO,LOG_WARNING,LOG_ERR,LOG_CRIT。fmt：格式化字符串，类似于printf的格式化字符串。...：可变参数列表，与格式化字符串对应。
本附录 A 提供了 Kore Web 框架常用 API 的简要参考，更详细的 API 文档和使用说明，请参考 Kore Web 框架的官方文档。
附录 B： 常见问题解答 (FAQ) ❓
1. Kore Web 框架是什么？ 🤔
Kore Web 框架是一个使用 C 语言 开发的，专为构建高性能、安全和可扩展的 Web 应用而设计的 Web 框架（Web Framework）。它以其卓越的性能、精简的代码库和灵活性而著称，适用于构建各种 Web 服务，特别是对性能和安全性有较高要求的应用场景。
2. Kore 框架有哪些主要特点和优势？ ✨
Kore 框架的主要特点和优势包括：
① 高性能（High Performance）：基于 C 语言 开发，拥有出色的性能和效率。
② 安全性（Security）：注重安全设计，代码库精简，降低安全风险。
③ 灵活性（Flexibility）：提供丰富的 API 和扩展机制，满足各种定制化需求。
④ 轻量级（Lightweight）：资源占用少，启动速度快，适合资源受限环境。
⑤ 实时性（Real-time）：原生支持 WebSocket，方便构建实时应用。
3. Kore 框架适用于哪些应用场景？ 🌐
Kore 框架适用于多种应用场景，包括：
① 高性能 API 服务（High-Performance API Services）：构建需要处理高并发请求和快速响应的 API 服务。
② 实时应用（Real-time Applications）：构建在线聊天、实时数据推送等实时性要求高的应用。
③ 嵌入式系统和物联网 (IoT)（Embedded Systems and IoT）：在资源受限的设备上运行 Web 服务。
④ 安全敏感型应用（Security-Sensitive Applications）：构建对安全性要求极高的应用。
⑤ 微服务（Microservices）：构建高性能的微服务。
4. 如何安装和搭建 Kore 开发环境？ 🛠️
搭建 Kore 开发环境通常包括以下步骤：
① 安装前提条件（Prerequisites）：确保已安装 C 编译器（如 gcc 或 clang）、 make、 openssl、 pcre、 zlib 等依赖库。
② 下载 Kore 源代码（Download Source Code）：从 GitHub 仓库（GitHub Repository）克隆 Kore 源代码。
③ 编译和安装 Kore（Compile and Install）：在 Kore 源代码目录下执行 make 命令进行编译，然后执行 sudo make install 命令进行安装。
④ 验证安装（Verify Installation）：编译并运行一个简单的 Kore 应用，验证环境是否搭建成功。
详细步骤请参考 chapter 1.4 环境搭建与快速开始。
5. Kore 的配置文件 kore.conf 有什么作用？ ⚙️
kore.conf 文件是 Kore Web 框架的 配置文件（Configuration File），用于配置 Kore 应用的各种运行时参数，包括：
① 服务器配置（Server Configuration）：监听地址、端口、工作进程数等。
② 日志配置（Log Configuration）：访问日志、错误日志文件路径。
③ TLS/HTTPS 配置（TLS/HTTPS Configuration）：证书和私钥路径。
④ 数据库连接配置（Database Connection Configuration）：数据库驱动、连接信息等。
⑤ 会话管理配置（Session Management Configuration）： Cookie 名称、超时时间等。
⑥ 模块加载配置（Module Loading Configuration）：加载 C 扩展模块。
通过修改 kore.conf 文件，可以灵活地调整 Kore 应用的行为。
6. 如何处理 HTTP 请求和响应？ 📤📥
在 Kore Web 框架中， HTTP 请求 和 响应 通过 struct http_request 对象进行处理。
① 接收请求（Receiving Request）：Kore 服务器自动接收和解析 HTTP 请求，并将请求信息封装到 struct http_request 对象中。
② 获取请求信息（Get Request Information）：使用 http_request_* 系列 API 从 struct http_request 对象中获取请求方法、路径、头部、查询参数、请求体等信息。
③ 构建响应（Build Response）：使用 http_response_* 系列 API 构建 HTTP 响应，设置状态码、头部、响应体等。
④ 发送响应（Send Response）：Kore 服务器自动将构建好的 HTTP 响应 发送回客户端。
详细 API 请参考 附录 A： Kore API 参考 和 chapter 3： Kore API 详解 - HTTP 处理。
7. Kore 如何进行路由 (Routing) 配置？ 🧭
Kore 使用 kore_http_handler_add() 和 kore_http_handler_add_regex() 函数进行 路由配置（Routing Configuration），将不同的 URL 路径映射到不同的 处理器函数（Handler Function）。
① 静态路由（Static Routing）：使用 kore_http_handler_add() 函数添加静态路由，将固定的 URL 路径映射到处理器函数。
② 动态路由（Dynamic Routing）：在 kore_http_handler_add() 函数的路径中使用尖括号 <> 定义 路径参数（Path Parameters），例如 /user/<id>。
③ 正则表达式路由（Regular Expression Routing）：使用 kore_http_handler_add_regex() 函数添加正则表达式路由，使用 正则表达式（Regular Expression）匹配 URL 路径。
详细路由配置请参考 chapter 2.2 路由 (Routing)。
8. 什么是中间件 (Middleware)？如何使用？ 🔗
中间件（Middleware）是在 HTTP 请求 处理流程中插入的组件，用于执行通用的、横切关注点的任务，例如日志记录、身份验证、请求头修改等。
① 注册全局中间件（Register Global Middleware）：使用 kore_http_middleware_register() 函数注册 全局中间件，应用于所有 HTTP 请求。
② 注册路由中间件（Register Route Middleware）：使用 kore_http_handler_add_middleware() 函数注册 路由中间件，只应用于特定的路由规则。
③ 编写中间件函数（Write Middleware Function）：编写符合 Kore 中间件函数规范的 C 函数，处理请求和响应。
详细中间件使用请参考 chapter 2.3 中间件 (Middleware) 和 chapter 9.1 自定义中间件 (Custom Middleware)。
9. Kore 如何集成数据库？ 🗄️
Kore Web 框架通过 数据库驱动（Database Driver）和 数据库 API（Database API）集成多种 关系型数据库（Relational Database），例如 PostgreSQL, MySQL, SQLite3。
① 配置数据库连接（Configure Database Connection）：在 kore.conf 文件中配置数据库连接信息，包括驱动、主机、端口、用户名、密码、数据库名称等。
② 获取数据库连接对象（Get Database Connection Object）：使用 kore_database_get() 函数获取已配置的数据库连接对象。
③ 执行 SQL 查询（Execute SQL Query）：使用 kore_database_query() 或 kore_database_query_async() 函数执行 SQL 查询。
④ 处理查询结果（Process Query Result）：使用 kore_database_result_* 系列 API 处理查询结果集。
详细数据库集成请参考 chapter 4.1 数据库集成 (Database Integration) 和 附录 A： Kore API 参考。
10. 如何进行 WebSocket 开发？ 💬
Kore Web 框架原生支持 WebSocket 协议，可以方便地构建实时应用。
① 添加 WebSocket 路由（Add WebSocket Route）：使用 kore_websocket_handler_add() 函数添加 WebSocket 路由，将指定的路径映射到 WebSocket 处理器函数。
② 编写 WebSocket 处理器函数（Write WebSocket Handler Function）：编写 C 函数 处理 WebSocket 连接 请求，执行 WebSocket 握手（Handshake），设置 消息接收回调函数 和 连接关闭回调函数。
③ 发送 WebSocket 消息（Send WebSocket Message）：使用 websocket_send_message() 函数向 WebSocket 连接 发送消息。
④ 关闭 WebSocket 连接（Close WebSocket Connection）：使用 websocket_close() 函数关闭 WebSocket 连接。
详细 WebSocket 开发请参考 chapter 5.3 WebSocket 支持 和 附录 A： Kore API 参考。
11. 如何进行性能优化？ 🚀
Kore Web 框架本身就具有高性能，但仍然可以通过一些策略进一步优化性能：
① 代码优化（Code Optimization）：优化代码逻辑、算法和数据结构，减少不必要的计算和内存分配。
② 数据库优化（Database Optimization）：优化 SQL 查询语句、添加索引、使用连接池。
③ 缓存（Caching）：使用 缓存 缓存 frequently accessed data，减少数据库访问和计算量。
④ HTTP 优化（HTTP Optimization）：启用 HTTP 压缩、 Keep-Alive、 CDN 等。
⑤ 异步和并发（Asynchronous and Concurrent）：充分利用 Kore 的 异步非阻塞 I/O 和 多进程模型。
⑥ 负载均衡和反向代理（Load Balancing and Reverse Proxy）：使用 负载均衡 和 反向代理 分发请求和缓存静态资源。
详细性能优化请参考 chapter 9.3 性能优化 (Performance Optimization) 和 chapter 8.3 性能测试 (Performance Testing)。
12. 如何进行错误排查和调试？ 🐞
Kore Web 应用的 错误排查和调试 可以通过以下方法进行：
① 查看日志（View Logs）：查看 Kore 应用的错误日志和访问日志，获取错误信息和请求访问记录。
② 使用调试器 (gdb)（Use Debugger (gdb)）：使用 gdb 调试器单步执行代码、查看变量值、设置断点。
③ 使用性能分析工具 (perf, gprof)（Use Profiling Tools (perf, gprof)）：使用 perf 或 gprof 性能分析工具分析性能瓶颈。
④ 使用网络分析工具 (tcpdump, Wireshark)（Use Network Analysis Tools (tcpdump, Wireshark)）：使用 tcpdump 或 Wireshark 网络分析工具捕获和分析网络数据包。
⑤ 遵循故障排查流程（Follow Troubleshooting Workflow）：按照 重现问题、 隔离问题、 分析日志和指标、 单步调试 的流程进行故障排查。
详细错误排查和调试请参考 chapter 11： Troubleshooting and Debugging。
希望以上 常见问题解答 (FAQ) 能够帮助您更好地理解和使用 Kore Web 框架。 如果您还有其他问题，请参考本书的其他章节或查阅 Kore Web 框架的官方文档。 📚