HttpServer HTTP 服务端 API 文档

HttpServer 是 EasyBot 提供的 HTTP 服务端 API，用于在插件中创建和管理 HTTP 服务器，支持路由注册、请求处理等功能。

核心类型

HttpRequestHandler 类型

HTTP 请求处理函数类型：

type HttpRequestHandler = (request: RequestMessage, response: ResponseMessage) => void | ResponseMessage;

HttpServerApi 接口

HTTP 服务器管理接口，提供服务器创建、启动、路由注册等功能。

服务器管理

CreateServer()

功能: 创建 HTTP 服务器

语法: CreateServer(port: number, id?: string, host?: string): string

参数:

port (number): 监听端口
id (string, 可选): 服务器ID，为空则自动生成
host (string, 可选): 监听地址，默认为 localhost

返回值: string - 服务器ID

示例:

const serverId = httpServer.CreateServer(8080, "my-server", "localhost");
logger.info("服务器ID:", serverId);

StartServerAsync()

功能: 启动 HTTP 服务器

语法: StartServerAsync(id: string): Promise<boolean>

参数:

id (string): 服务器ID

返回值: Promise<boolean> - 是否启动成功

示例:

const started = await httpServer.StartServerAsync("my-server");
if (started) {
    logger.info("服务器启动成功");
}

StopServerAsync()

功能: 停止 HTTP 服务器

语法: StopServerAsync(id: string): Promise<boolean>

参数:

id (string): 服务器ID

返回值: Promise<boolean> - 是否停止成功

示例:

const stopped = await httpServer.StopServerAsync("my-server");
if (stopped) {
    logger.info("服务器已停止");
}

DestroyServerAsync()

功能: 销毁服务器

语法: DestroyServerAsync(serverId: string): Promise<boolean>

参数:

serverId (string): 服务器ID

返回值: Promise<boolean> - 是否销毁成功

示例:

const destroyed = await httpServer.DestroyServerAsync("my-server");

路由注册

OnGet()

功能: 注册 GET 请求路由

语法: OnGet(serverId: string, path: string, handler: HttpRequestHandler): boolean

参数:

serverId (string): 服务器ID
path (string): 路径
handler (HttpRequestHandler): 处理函数

返回值: boolean - 是否注册成功

示例:

const success = httpServer.OnGet("my-server", "/api/users", (req, res) => {
    res.status = 200;
    res.body = JSON.stringify({ users: ["Steve", "Alex"] });
});

OnPost()

功能: 注册 POST 请求路由

语法: OnPost(serverId: string, path: string, handler: HttpRequestHandler): boolean

参数:

serverId (string): 服务器ID
path (string): 路径
handler (HttpRequestHandler): 处理函数

返回值: boolean - 是否注册成功

示例:

httpServer.OnPost("my-server", "/api/users", (req, res) => {
    const userData = JSON.parse(req.body || "{}");
    res.status = 201;
    res.body = JSON.stringify({ message: "用户创建成功", user: userData });
});

OnPut()

功能: 注册 PUT 请求路由

语法: OnPut(serverId: string, path: string, handler: HttpRequestHandler): boolean

参数:

serverId (string): 服务器ID
path (string): 路径
handler (HttpRequestHandler): 处理函数

返回值: boolean - 是否注册成功

示例:

httpServer.OnPut("my-server", "/api/users/:id", (req, res) => {
    res.status = 200;
    res.body = JSON.stringify({ message: "用户更新成功" });
});

OnDelete()

功能: 注册 DELETE 请求路由

语法: OnDelete(serverId: string, path: string, handler: HttpRequestHandler): boolean

参数:

serverId (string): 服务器ID
path (string): 路径
handler (HttpRequestHandler): 处理函数

返回值: boolean - 是否注册成功

示例:

httpServer.OnDelete("my-server", "/api/users/:id", (req, res) => {
    res.status = 204;
    res.body = "";
});

OnRequest()

功能: 注册任意 HTTP 方法的路由

语法: OnRequest(serverId: string, method: string, path: string, handler: HttpRequestHandler): boolean

参数:

serverId (string): 服务器ID
method (string): HTTP方法
path (string): 路径
handler (HttpRequestHandler): 处理函数

返回值: boolean - 是否注册成功

示例:

httpServer.OnRequest("my-server", "PATCH", "/api/users/:id", (req, res) => {
    res.status = 200;
    res.body = JSON.stringify({ message: "部分更新成功" });
});

OffRequest()

功能: 取消注册路由

语法: OffRequest(serverId: string, method: string, path: string): boolean

参数:

serverId (string): 服务器ID
method (string): HTTP方法
path (string): 路径

返回值: boolean - 是否取消成功

示例:

const removed = httpServer.OffRequest("my-server", "GET", "/api/users");

服务器状态查询

IsServerRunning()

功能: 获取服务器状态

语法: IsServerRunning(serverId: string): boolean

参数:

serverId (string): 服务器ID

返回值: boolean - 服务器是否运行中

示例:

if (httpServer.IsServerRunning("my-server")) {
    logger.info("服务器正在运行");
}

GetServerAddress()

功能: 获取服务器地址

语法: GetServerAddress(serverId: string): string

参数:

serverId (string): 服务器ID

返回值: string - 服务器地址

示例:

const address = httpServer.GetServerAddress("my-server");
logger.info("服务器地址:", address);

GetServerIds()

功能: 获取所有服务器ID

语法: GetServerIds(): string[]

返回值: string[] - 服务器ID列表

示例:

const serverIds = httpServer.GetServerIds();
logger.info("所有服务器:", serverIds);

使用示例

创建简单的 API 服务器

// 创建服务器
const serverId = httpServer.CreateServer(8080, "api-server");

// 注册路由
httpServer.OnGet(serverId, "/api/status", (req, res) => {
    res.status = 200;
    res.headers.Set("Content-Type", "application/json");
    res.body = JSON.stringify({ status: "ok", timestamp: new Date() });
});

httpServer.OnPost(serverId, "/api/data", (req, res) => {
    const data = JSON.parse(req.body || "{}");
    res.status = 200;
    res.body = JSON.stringify({ received: data });
});

// 启动服务器
await httpServer.StartServerAsync(serverId);
logger.info("API服务器已启动:", httpServer.GetServerAddress(serverId));

处理请求参数和头部

httpServer.OnPost(serverId, "/api/upload", (req, res) => {
    // 检查Content-Type
    const contentType = req.headers.Get("Content-Type");
    
    if (!contentType.includes("application/json")) {
        res.status = 400;
        res.body = JSON.stringify({ error: "Content-Type必须是application/json" });
        return;
    }
    
    // 处理请求体
    try {
        const data = JSON.parse(req.body || "{}");
        
        // 设置响应头部
        res.headers.Set("Content-Type", "application/json");
        res.status = 200;
        res.body = JSON.stringify({ message: "上传成功", data: data });
    } catch (error) {
        res.status = 400;
        res.body = JSON.stringify({ error: "JSON格式错误" });
    }
});

服务器生命周期管理

async function manageServer() {
    const serverId = httpServer.CreateServer(3000, "temp-server");
    
    // 注册路由
    httpServer.OnGet(serverId, "/", (req, res) => {
        res.status = 200;
        res.body = "Hello World!";
    });
    
    // 启动服务器
    const started = await httpServer.StartServerAsync(serverId);
    if (!started) {
        logger.error("服务器启动失败");
        return;
    }
    
    logger.info("服务器运行状态:", httpServer.IsServerRunning(serverId));
    
    // 运行一段时间后停止
    setTimeout(async () => {
        await httpServer.StopServerAsync(serverId);
        await httpServer.DestroyServerAsync(serverId);
        logger.info("服务器已销毁");
    }, 60000); // 1分钟后停止
}

动态路由管理

const serverId = httpServer.CreateServer(8080);

// 添加路由
httpServer.OnGet(serverId, "/api/test", (req, res) => {
    res.status = 200;
    res.body = "测试路由";
});

// 启动服务器
await httpServer.StartServerAsync(serverId);

// 稍后移除路由
setTimeout(() => {
    const removed = httpServer.OffRequest(serverId, "GET", "/api/test");
    logger.info("路由移除结果:", removed);
}, 30000);

注意事项

端口冲突: 确保端口未被其他服务占用
异步操作: 服务器启动、停止、销毁都是异步操作
路由顺序: 路由按注册顺序匹配，注意路径的优先级
错误处理: 在处理函数中进行适当的错误处理
资源清理: 插件卸载时记得停止和销毁服务器
安全考虑: 注意输入验证和访问控制

最佳实践

使用有意义的服务器ID便于管理
设置合适的HTTP状态码和响应头
对请求体进行验证和错误处理
在插件卸载时清理服务器资源
使用JSON格式进行数据交换

核心类型​

HttpRequestHandler 类型​

HttpServerApi 接口​

服务器管理​

CreateServer()​

StartServerAsync()​

StopServerAsync()​

DestroyServerAsync()​

路由注册​

OnGet()​

OnPost()​

OnPut()​

OnDelete()​

OnRequest()​

OffRequest()​

服务器状态查询​

IsServerRunning()​

GetServerAddress()​

GetServerIds()​

使用示例​

创建简单的 API 服务器​

处理请求参数和头部​

服务器生命周期管理​

动态路由管理​

注意事项​

最佳实践​

核心类型

HttpRequestHandler 类型

HttpServerApi 接口

服务器管理

CreateServer()

StartServerAsync()

StopServerAsync()

DestroyServerAsync()

路由注册

OnGet()

OnPost()

OnPut()

OnDelete()

OnRequest()

OffRequest()

服务器状态查询

IsServerRunning()

GetServerAddress()

GetServerIds()

使用示例

创建简单的 API 服务器

处理请求参数和头部

服务器生命周期管理

动态路由管理

注意事项

最佳实践