接口参考

本文档详细说明 PostForwarder 的输入输出接口格式。

接收端口

PostForwarder 在监听端口（默认 1403）上接收来自手机端的请求。

请求

• URL：http://<电脑IP>:<端口>/<任意路径>
• 方法：POST（推荐），也支持 GET/PUT/DELETE/PATCH
• Content-Type：application/x-www-form-urlencoded

请求体格式

请求体为 URL 编码的表单数据，其中必须包含 content 字段：

from=<发送者>&content=<URL编码的JSON>

字段	说明	是否必需
content	URL 编码后的 JSON 内容	是
from	发送者标识（如手机号）	否

请求示例

POST http://192.168.1.50:1403/sms
Content-Type: application/x-www-form-urlencoded

from=10329362791&content=%7B%22id%22%3A%20%22message%22%2C%20%22title%22%3A%20%2210329362791%22%2C%20%22subtitle%22%3A%20%22test%22%2C%20%22kind%22%3A%20%22%E7%9F%AD%E4%BF%A1%22%7D

转发到目标服务

PostForwarder 提取 content 字段并 URL 解码后，以 JSON 形式转发到固定目标。

转发请求

• URL：http://127.0.0.1:47300/api/activities
• 方法：与原始请求相同
• Content-Type：application/json; charset=utf-8
• 请求体：URL 解码后的 content 内容

转发请求示例

POST http://127.0.0.1:47300/api/activities
Content-Type: application/json; charset=utf-8

{"id": "message", "title": "10329362791", "subtitle": "test", "kind": "短信"}

响应处理

目标服务的响应会被原样回传给手机端：

• 状态码：保持目标服务的状态码
• 响应头：去掉 hop-by-hop 头和 content-encoding
• 响应体：原样返回

错误响应

403 Forbidden — IP 不在白名单

当来源 IP 不在白名单中时，返回此错误：

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "error": "forbidden",
  "detail": "IP 192.168.1.200 not in whitelist"
}

502 Bad Gateway — 转发失败

当无法连接到目标服务或转发超时（30 秒）时，返回此错误：

HTTP/1.1 502 Bad Gateway
Content-Type: application/json; charset=utf-8

{
  "error": "bad gateway",
  "detail": "HTTPConnectionPool(host='127.0.0.1', port=47300): Max retries exceeded with url: /api/activities"
}

curl 测试示例

发送测试请求

将 <电脑IP> 替换为运行 PostForwarder 的电脑 IP，将白名单 IP 替换为你的手机或测试机 IP：

curl -X POST http://<电脑IP>:1403/test \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'from=10329362791' \
  --data-urlencode 'content={"id":"message","title":"10329362791","subtitle":"test","kind":"短信"}'

测试非白名单 IP

curl -X POST http://127.0.0.1:1403/test \
  -d "content=hello"
# 返回 403（如果 127.0.0.1 不在白名单中）

URL 编码对照表

原始字符	URL 编码	说明
{	%7B	JSON 左花括号
}	%7D	JSON 右花括号
"	%22	JSON 双引号
:	%3A	冒号
,	%2C	逗号
	%20	空格
短信	%E7%9F%AD%E4%BF%A1	中文字符（UTF-8）