第 5 章：路由与回调返回值

本章说明路由 key、HTTP 状态码、处理阶段和 STTNet 流程返回值之间的区别。

1. 默认路由不区分 method

setFunction("/users", ...) 默认按 request.loc 匹配，因此 GET、POST、DELETE /users 都会进入同一个 key。HTTP method 可在回调内部判断，也可纳入自定义路由 key。

2. 同一路由的多个阶段

server.setFunction("/admin",
    [](HttpServerFDHandler &client, HttpRequestInformation &request) {
        // 第一阶段负责认证；未通过时发送 401，并用 -1 结束后续阶段。
        if(request.headerValue("authorization").empty())
            return client.sendText("unauthorized", "401 Unauthorized") ? -1 : -2;

        // 1 表示本阶段通过，继续执行同一路由的下一阶段。
        return 1;
    });

server.setFunction("/admin",
    [](HttpServerFDHandler &client, HttpRequestInformation &) {
        // 只有第一阶段返回 1 时才会执行到这里。
        return client.sendText("admin area") ? 1 : -2;
    });

认证拒绝后的返回值：发送 401 后返回 1 会继续执行后续业务阶段，可能产生第二个响应或绕过认证；已发送拒绝响应时可返回 -1 结束本次流程。

3. 返回值与连接行为

返回值	同步阶段	Worker 阶段完成后
1	进入下一阶段；没有下一阶段时结束本次流程。	恢复并进入下一阶段。
0	表示已经调用 putTask，等待 Worker。	Worker 回调的有效完成结果为 `1`、`-1` 或 `-2`；`0` 仅表示同步阶段已投递 Worker。
-1	丢弃本次流程剩余阶段，连接保持可复用。	丢弃本次流程剩余阶段，连接保持。
-2	流程停止，连接关闭。	流程停止，连接关闭。

4. 自定义 method + path key

server.setGetKeyFunction(
    [](HttpServerFDHandler &, HttpRequestInformation &request) {
        request.ctx["key"] = request.type + " " + request.loc;
        return 1;
    });

server.setFunction("GET /users", getUsers);
server.setFunction("POST /users", createUser);

5. 错误处理原则

用户输入错误返回稳定的 4xx JSON，不泄露内部路径、SQL 或密钥。
内部异常返回 500，并在服务端日志记录可定位信息。
发送失败对应 -2；业务拒绝且响应已发送时，-1 表示后续阶段停止。
服务级 server.close() 由主线程或控制线程调用，不属于 Reactor 请求回调的职责。