PawnREST - HTTP/S 文件传输与 REST API

[siwode]

PawnREST - HTTP/S 文件传输与 REST API 框架

一个为 SA-MP/open.mp 服务器提供 HTTP/S 文件上传下载功能以及完整 REST API 框架的插件。
下载地址 https://github.com/Fanorisky/PawnREST

---

Wiki 文档

API 文档与使用指南位于：

代码:

wiki/

---

Pawn 示例脚本

示例脚本位于：

代码:

example/

• 01_server_routes.pwn - 自定义 REST 路由示例
  
• 02_file_routes_and_ops.pwn - 文件路由与文件操作示例
  
• 03_json_nodes.pwn - JSON 节点创建与响应示例
  
• 04_outbound_uploads.pwn - 外部文件上传示例
  
• 05_outbound_requests.pwn - HTTP/S 请求客户端示例
  
• 06_websocket_client.pwn - WebSocket 客户端示例
  
• 07_crc_utils.pwn - CRC32 校验与文件比较工具
  
• 08_request_input_fallbacks.pwn - 请求参数读取示例
  
• 09_discord_webhook.pwn - Discord Webhook 集成示例
  

---

✨ 功能特性

• 文件上传服务器 - 通过 HTTP POST 接收文件并进行验证
  
• 文件下载 API - 通过 HTTP GET 提供文件下载
  
• 外部文件上传 - 上传文件到第三方服务器
  
• 上传客户端 - 复用基础 URL 与默认请求头
  
• HTTP 请求客户端 - REST_Request / REST_RequestJSON
  
• WebSocket 客户端 - 支持 ws:// 与 wss://
  
• REST API 框架 - 支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS
  
• 强大的请求访问器 - URL 查询参数与 Header 解析
  
• 纯节点 JSON API - JSON 构建与解析
  
• 鉴权系统 - Bearer Token 路由认证
  
• HTTPS/TLS 支持 - OpenSSL 支持
  
• 结构化错误回调 - 提供详细错误信息
  
• CRC32 完整性校验 - 文件校验验证
  

---

安装方法

1. 下载适用于你平台的最新版本（Windows 为 .dll，Linux 为 .so）
   
2. 放入 open.mp 服务器的 components 目录
   
3. 将 PawnREST.inc 放入 Pawn 编译器 include 目录
   
4. 在脚本中添加：
   

代码:

#include <PawnREST>

公共 API 使用以下前缀：

代码:

REST_*  // HTTP 与 REST 功能
FILE_*  // 文件上传下载功能

---

快速开始

代码:

#include <open.mp>
#include <PawnREST>
new g_MapRoute = -1;
new g_ApiPlayers = -1;
public OnGameModeInit()
{
    REST_Start(8080);
    g_MapRoute = FILE_RegisterRoute(
        "/maps",
        "scriptfiles/maps/",
        ".map,.json",
        50
    );
    FILE_AddAuthKey(g_MapRoute, "upload-secret-key");
    FILE_AllowList(g_MapRoute, true);
    FILE_AllowDownload(g_MapRoute, true);
    g_ApiPlayers = REST_RegisterAPIRoute(
        HTTP_METHOD_GET,
        "/api/players",
        "OnGetPlayers"
    );
    REST_SetRouteAuthKey(g_ApiPlayers, "api-secret-key");
    return 1;
}

---

HTTP 方法常量

常量	对应方法
HTTP_METHOD_GET	GET
HTTP_METHOD_POST	POST
HTTP_METHOD_PUT	PUT
HTTP_METHOD_PATCH	PATCH
HTTP_METHOD_DELETE	DELETE
HTTP_METHOD_HEAD	HEAD
HTTP_METHOD_OPTIONS	OPTIONS

---

文件上传路由

支持：

• 上传文件
  
• 文件列表
  
• 文件下载
  
• 文件删除
  
• 文件信息查询
  
• CRC32 校验
  
• 上传鉴权
  
• 冲突处理策略
  

主要函数：

代码:

FILE_RegisterRoute(...)
FILE_AddAuthKey(...)
FILE_AllowList(...)
FILE_AllowDownload(...)
FILE_AllowDelete(...)
FILE_AllowInfo(...)
FILE_Delete(...)
FILE_GetCount(...)
FILE_GetSize(...)

---

REST API 路由

注册自定义接口：

代码:

REST_RegisterAPIRoute(
    HTTP_METHOD_GET,
    "/api/server",
    "OnGetServer"
);

支持：

• GET
  
• POST
  
• PUT
  
• PATCH
  
• DELETE
  
• HEAD
  
• OPTIONS
  

支持 URL 参数：

代码:

/api/player/{id}

示例：

代码:

/api/player/5

---

请求数据读取

支持：

• 客户端 IP
  
• HTTP 方法
  
• 请求路径
  
• 请求体 Body
  
• URL 参数
  
• Query 参数
  
• HTTP Header
  

例如：

代码:

REST_GetParamInt(requestId, "id");
REST_GetQueryInt(requestId, "page");
REST_GetHeader(requestId, "Authorization");

---

JSON API

特点：

• 纯 Node 节点系统
  
• JSON 解析
  
• JSON 构建
  
• 对象与数组操作
  
• 序列化输出
  

创建对象：

代码:

new payload = JsonObject(
    "name", JsonString("PawnREST"),
    "version", JsonString("1.0")
);

---

响应函数

代码:

Respond(...)
RespondJSON(...)
RespondNode(...)
RespondError(...)
SetResponseHeader(...)

---

☁️ 外部 HTTP 请求

支持：

• HTTP 请求
  
• JSON 请求
  
• 请求取消
  
• 请求状态查询
  
• 错误信息获取
  

主要函数：

代码:

REST_CreateRequestClient(...)
REST_Request(...)
REST_RequestJSON(...)

---

WebSocket 客户端

支持：

• 文本 WebSocket
  
• JSON WebSocket
  
• TLS/WSS
  
• 发送消息
  
• 关闭连接
  

主要函数：

代码:

REST_WebSocketClient(...)
REST_JsonWebSocketClient(...)
REST_WebSocketSend(...)
REST_JsonWebSocketSend(...)

---

CRC32 工具

代码:

FILE_VerifyCRC32(...)
FILE_GetCRC32(...)
FILE_Compare(...)

用于：

• 文件完整性验证
  
• 上传校验
  
• 文件比较
  

---

回调列表

上传相关：

代码:

OnIncomingUploadCompleted
OnIncomingUploadFailed
OnIncomingUploadProgress
OnOutgoingUploadStarted
OnOutgoingUploadProgress
OnOutgoingUploadCompleted
OnOutgoingUploadFailed

请求相关：

代码:

OnRequestFailure
OnWebSocketDisconnect

---

内置接口

接口	说明
GET /health	健康检查
GET /stats	服务器统计
GET {route}/files	获取文件列表
GET {route}/files/{name}	下载文件
GET {route}/files/{name}/info	获取文件信息
DELETE {route}/files/{name}	删除文件

---

鸣谢

• yhirose - HTTP 库
  
• Southclaws - pawn-requests API 参考
  
• Fanorisky - 项目实现
  
• SA-MP Team
  
• open.mp Contributors