外部 API 调用

[🕒 预计 25 分钟] | 难度：进阶

LingBuilder 通过 HTTP 客户端 模块（模块 ID：lingbuilder.net.http-client，当前 2.0）调用外部 RESTful API，配合 JSON 模块 解析响应数据。两个模块都可在侧边栏模块组的模块市场中获取；项目还需在 配置项目所使用模块 中启用它们。

模块基于 WinHTTP，客户端、请求和原生句柄由运行时管理，.lcpp 里只使用稳定的整数 ID。异步完成处理器统一在 UI 消息线程执行，因此可以直接更新控件。

NOTE

以下示例均为 专业模式（中文代码编辑器）源码。.lcpp 使用缩进 + 结束 表达代码块，不使用花括号；注释写 //。

1. 核心命令一览

HTTP 客户端模块采用"客户端 → 请求 → 异步执行 → 完成处理器"的函数式风格，常用命令：

命令	签名
`HTTP客户端_创建客户端`	`HTTP客户端_创建客户端()`
`HTTP客户端_设置超时`	`HTTP客户端_设置超时(客户端, 解析毫秒, 连接毫秒, 发送毫秒, 接收毫秒)`
`HTTP客户端_设置UserAgent`	`HTTP客户端_设置UserAgent(客户端, UserAgent)`
`HTTP客户端_设置默认请求头`	`HTTP客户端_设置默认请求头(客户端, 名称, 值)`
`HTTP客户端_创建请求`	`HTTP客户端_创建请求(客户端, 方法, 地址)`
`HTTP客户端_设置请求头` / `HTTP客户端_添加请求头`	`(请求, 名称, 值)`
`HTTP客户端_设置文本正文`	`HTTP客户端_设置文本正文(请求, 正文, 内容类型)`
`HTTP客户端_设置JSON正文`	`HTTP客户端_设置JSON正文(请求, JSON)`
`HTTP客户端_绑定完成处理器`	`HTTP客户端_绑定完成处理器(请求, &处理器)`
`HTTP客户端_开始请求`	`HTTP客户端_开始请求(请求)`
`HTTP客户端_GET异步`	`HTTP客户端_GET异步(客户端, 地址, &处理器)`
`HTTP客户端_POSTJSON异步`	`HTTP客户端_POSTJSON异步(客户端, 地址, JSON, &处理器)`
`HTTP客户端_取当前请求`	`HTTP客户端_取当前请求()`
`HTTP客户端_请求是否成功`	`HTTP客户端_请求是否成功(请求)`
`HTTP客户端_取响应状态码`	`HTTP客户端_取响应状态码(请求)`
`HTTP客户端_取响应文本编码`	`HTTP客户端_取响应文本编码(请求, 编码)`
`HTTP客户端_取请求错误`	`HTTP客户端_取请求错误(请求)`
`HTTP客户端_销毁请求` / `HTTP客户端_销毁客户端`	`(请求)` / `(客户端)`

JSON 模块常用命令：JSON_是否有效、JSON_解析、JSON_对象_取、JSON_取文本值、JSON_取整数值、JSON_对象_键列表、JSON_序列化、JSON_释放。

IMPORTANT

处理器参数必须使用 &处理器名 引用语法（如 &请求完成），不要写成带引号的字符串；被引用的处理器必须无参数且返回 空。

2. 发送异步 GET 请求

最简单的写法是用 HTTP客户端_GET异步，它内部完成"创建请求 → 开始请求"，并直接返回请求 ID：

lcpp

事件 _按钮1_被单击()
    局部 HTTP客户端 客户端 = HTTP客户端_创建客户端()
    HTTP客户端_设置超时(客户端, 10000, 15000, 30000, 30000)
    HTTP客户端_设置默认请求头(客户端, "Accept", "application/json")
    HTTP客户端_GET异步(客户端, "https://api.example.com/data", &请求完成)
结束

空 请求完成()
    局部 HTTP客户端请求 当前请求 = HTTP客户端_取当前请求()
    如果 (HTTP客户端_请求是否成功(当前请求))
        控件_设置文本(标签1, HTTP客户端_取响应文本编码(当前请求, "auto"))
    否则
        调试输出(HTTP客户端_取请求错误(当前请求))
    如果结束
结束

NOTE

完成处理器没有入参，请求 ID 通过 HTTP客户端_取当前请求() 取得。响应快照在处理器执行期间保持可读。 控件_设置文本 这类参数的真实语义是引用设计器里的控件，因此控件名写成不带引号的裸标识符。

3. 发送 POST JSON

需要自定义方法、请求头或正文时，改用显式请求对象：

lcpp

事件 _提交按钮_被单击()
    局部 文本型 令牌 = "读取自配置文件的访问令牌"
    局部 HTTP客户端 客户端 = HTTP客户端_创建客户端()
    局部 HTTP客户端请求 请求 = HTTP客户端_创建请求(客户端, "POST", "https://api.example.com/submit")
    HTTP客户端_设置请求头(请求, "Authorization", "Bearer " + 令牌)
    HTTP客户端_设置JSON正文(请求, "{\"name\":\"LingBuilder\"}")
    HTTP客户端_绑定完成处理器(请求, &提交完成)
    HTTP客户端_开始请求(请求)
结束

无自定义请求头时，也可以直接用一行式快捷入口：

lcpp

HTTP客户端_POSTJSON异步(客户端, "https://api.example.com/submit", "{\"name\":\"LingBuilder\"}", &提交完成)

4. 用 JSON 模块解析响应

HTTP客户端_取响应文本编码 返回的是 JSON 文本，需要先 JSON_解析 成 JSON值，再按类型读取成员：

lcpp

空 解析响应()
    局部 HTTP客户端请求 当前请求 = HTTP客户端_取当前请求()
    局部 文本型 正文 = HTTP客户端_取响应文本编码(当前请求, "auto")
    如果 (JSON_是否有效(正文) == 假)
        调试输出("响应不是合法 JSON：" + JSON_取最后错误())
    否则
        局部 JSON值 数据 = JSON_解析(正文)
        局部 文本型 名称 = JSON_取文本值(JSON_对象_取(数据, "name"), "")
        局部 整数型 数量 = JSON_取整数值(JSON_对象_取(数据, "count"), 0)
        控件_设置文本(标签1, "名称：" + 名称 + "，数量：" + 数量)
        JSON_释放(数据)
    如果结束
结束

JSON_对象_取 返回的是成员的深度副本，同样需要 JSON_释放；对象嵌套时逐层取出即可。

5. 安全建议

API Key 等敏感信息存放在配置文件或项目常量中，切勿硬编码到源码。
先判断 HTTP客户端_请求是否成功（传输成功且状态码在 200–299），再读取正文；正文进 JSON 模块前用 JSON_是否有效 校验，避免异常数据导致解析失败。
地址只接受 http:// 与 https://；运行时默认完整校验证书链、主机名、有效期和用途，禁止 HTTPS 降级到 HTTP。确有需要时才用 HTTP客户端_设置TLS策略、HTTP客户端_设置证书固定 显式放宽或固定。
Host、Content-Length、Connection、Transfer-Encoding、Cookie、Set-Cookie 由运行时管理，普通请求头无法覆盖。
用 HTTP客户端_设置超时 和 HTTP客户端_设置资源限制 约束耗时与内存占用。
HTTP客户端_执行同步、HTTP客户端_等待请求 仅用于后台任务或测试；窗口事件中不要阻塞等待，否则消息循环会卡住界面。

下一步

处理常见运行时错误：问题排查
优化程序性能：性能优化

外部 API 调用 ​

1. 核心命令一览 ​

2. 发送异步 GET 请求 ​

3. 发送 POST JSON ​

4. 用 JSON 模块解析响应 ​

5. 安全建议 ​

下一步 ​

外部 API 调用

1. 核心命令一览

2. 发送异步 GET 请求

3. 发送 POST JSON

4. 用 JSON 模块解析响应

5. 安全建议

下一步