fountain f_httpclient 实战指南:基于仓颉语言的 HTTP 客户端封装与调用

原创2026-10-14 16:57:002,241 阅读
文章标签:后端Web框架RPC框架认证鉴权任务调度ORM缓存抽象

fountain f_httpclient 实战指南:基于仓颉语言的 HTTP 客户端封装与调用

导读

f_httpclient 是 fountain 项目中面向服务器应用开发场景的 HTTP 客户端模块,它本质上是仓颉标准库扩展 stdx.net.http.Client 的一层轻量封装。本文围绕 f_httpclient/README.md 展开,完整梳理 HttpClient 的声明与链式调用方式、FormBuilder 与 MultipartFormDataBuilder 的表单/文件上传构造能力,以及 ExtendHttpResponse 提供的响应体读取与类型转换扩展。读完本文,你将掌握在仓颉工程中通过 fountain::f_httpclient 发起 GET/POST/PUT/DELETE 请求、携带请求头与超时配置、发送 application/x-www-form-urlencoded 与 multipart/form-data 数据、以及将响应体直接反序列化为 DataFields 类型实例的完整实战方法。


一、模块定位与依赖环境

f_httpclient 依赖 stdx.net.http(HTTP 客户端核心)、stdx.net.tls(TLS 配置)、stdx.encoding.url(URL 编码)等仓颉标准库扩展,同时依赖 fountain 自身的数据与媒体类型模块。从 f_httpclient/cjpm.toml 可以看到它的依赖清单:

[dependencies]
  "cangjie_tpc::charset4cj" = "1.0.5"
  "fountain::f_base" = {path = "../f_base"}
  "fountain::f_data" = {path = "../f_data"}
  "fountain::f_http" = {path = "../f_http"}

模块编译使用 --dy-std(动态标准库)选项,因此使用前必须配置动态标准库路径:

export CANGJIE_STDX_DYNAMIC_PATH=/path/to/dynamic_stdx

这与 fountain 项目"只需开发动态链接库、由 fboot 负责加载初始化"的整体设计一致(可参考 README.md 中模块依赖图与 模块依赖图/README.md)。

包路径约定:直接以 fountain::f_httpclient 使用本模块;项目根目录的聚合包 src/httpclient/httpclient.cj 重新导出了同名 API,因此也可以通过 fountain::fountain.httpclient 包路径使用(见 README.md)。


二、HttpClient 核心声明

HttpClient 继承了 Resource,声明如下(完整声明见 f_httpclient/src/httpclient.cj):

public class HttpClient <: Resource {
    // 全局读/写超时(静态,对所有实例生效)
    public static func globalReadTimeout(readTimeout: Duration): Unit
    public static func globalWriteTimeout(writeTimeout: Duration): Unit

    public HttpClient(var url: String)

    public func autoRedirect(auto: Bool): This
    public func connector(c: (SocketAddress) -> StreamingSocket): This
    public func cookieJar(cookieJar: ?CookieJar): This
    public func poolSize(size: Int64): This
    public func readTimeout(timeout: Duration): This
    public func writeTimeout(timeout: Duration): This
    public func tlsConfig(config: TlsClientConfig): This
    public func header(key: String, value: String): This
    public func header<T>(key: String, value: T): This where T <: ToString

    public func isClosed(): Bool
    public func close(): Unit

    public func get(): HttpResponse
    public func delete(): HttpResponse
    public func put(): HttpResponse
    public func put(body: String): HttpResponse
    public func put(body: InputStream): HttpResponse
    public func put(body: Array<Byte>): HttpResponse
    public func put<T>(contentType: String, body: T): HttpResponse where T <: DataFields<T>
    public func post(): HttpResponse
    public func post(body: String): HttpResponse
    public func post(body: InputStream): HttpResponse
    public func post(body: Array<Byte>): HttpResponse
    public func post<T>(contentType: String, body: T): HttpResponse where T <: DataFields<T>

    public func form(): FormBuilder
    public func multipartFormdata(): MultipartFormDataBuilder
}

2.1 全局超时与实例级超时

globalReadTimeout / globalWriteTimeout 是静态方法,设置的超时对所有后续创建的 HttpClient 实例生效。从 httpclient.cj 的实现可以看到,构造函数会读取静态超时并自动应用到当前实例:

private static var readTimeout_ = None<Duration>
private static var writeTimeout_ = None<Duration>
public static func globalReadTimeout(readTimeout: Duration): Unit {
    readTimeout_ = readTimeout
}
...
public HttpClient(var url: String){
    if(let Some(x) <- readTimeout_){
        readTimeout(x)
    }
    if(let Some(x) <- writeTimeout_){
        writeTimeout(x)
    }
}

实例方法 readTimeout / writeTimeout 则只影响当前实例,二者可结合使用:先通过静态方法设定全局默认值,再对个别请求用实例方法覆盖。

2.2 链式配置与"builder 模式"实现

HttpClient 内部维持两个组件(见 httpclient.cj):

private let builder = ClientBuilder()
private let request = HttpRequestBuilder()
  • 连接层配置(autoRedirect、connector、cookieJar、poolSize、readTimeout、writeTimeout、tlsConfig 等)直接委托给 ClientBuilder;
  • 请求层配置(header)委托给 HttpRequestBuilder。

所有配置方法都返回 This,因此天然支持链式调用。一个典型的完整配置示例:

let client = HttpClient("https://api.example.com/data")
    .autoRedirect(true)
    .poolSize(16)
    .readTimeout(5.seconds)
    .writeTimeout(5.seconds)
    .header("Accept", "application/json")
    .header("X-Request-Id", 1024)   // 泛型重载:任何 ToString 类型
    .tlsConfig(tls)

其中 header 有两个重载:字符串版本与泛型版本 header<T>(key, value) where T <: ToString,后者内部调用 value.toString()(见 httpclient.cj),免去了手动拼接字符串的麻烦。

2.3 请求执行与底层调用链

所有请求方法最终汇聚到私有方法 send(见 httpclient.cj):

private func send(method: String): HttpResponse {
    request.method(method).url(url)
    client = builder.build()
    (client?.send(request.build())).getOrThrow()
}
public func get(): HttpResponse { send('GET') }
public func delete(): HttpResponse { send('DELETE') }
public func put(): HttpResponse { send('PUT') }
public func post(): HttpResponse { send('POST') }

即:设置请求方法与 URL → 用 ClientBuilder 构建底层 Client → 发送请求并返回 HttpResponse。每次 send 都会重建 Client,因此 HttpClient 实例是可复用、可配置的,而 close() 会关闭底层连接并将 isClosed() 置为 true(httpclient.cj)。由于实现了 Resource,可以配合 resource(client, { ... }) 使用,确保请求结束后自动释放资源——f_llm 模块内部正是这样使用的(见下文第六节示例)。

2.4 请求体重载:String / InputStream / Array / DataFields

put / post 提供四类重载,覆盖了日常开发的主要场景:

  • 无参:发送空请求体;
  • body: String:直接以字符串作为请求体(request.body(body));
  • body: InputStream:以流形式发送,适合大文件或增量数据;
  • body: Array<Byte>:以原始字节发送;
  • <T>(contentType: String, body: T) where T <: DataFields<T>:自动按媒体类型序列化。

其中泛型版本是 fountain 数据体系的关键集成点(见 httpclient.cj):

private func body<T>(contentType: String, body: T): This where T <: DataFields<T> {
    let bytes = MediaTypes.tryParse(contentType).getOrThrow{
        MediaTypeException('${contentType} is not a valid media type')
    }.fromDataFields<T>(body)
    request.body(bytes)
    this
}
public func post<T>(contentType: String, body: T): HttpResponse where T <: DataFields<T> {
    header('Content-Type', contentType)
    this.body<T>(contentType, body).post()
}

实现流程为:先用 MediaTypes.tryParse(contentType) 将 contentType 字符串解析为 f_http 模块的 MediaType 实例(解析失败抛出 MediaTypeException),再调用 MediaType.fromDataFields<T>(body) 将泛型对象编码为字节数组,最后自动设置 Content-Type 请求头并发送。也就是说,只要你传入的对象实现了 f_data 的 DataFields<T> 接口(见 f_data/src/base/DataFields.cj,它是 FromToData 的子接口,要求提供 toData() 与 tryFromData() 静态方法),即可直接作为 JSON 等格式的请求体发送。

说明:MediaTypes 在 f_http 模块中默认注册了 text/plain、application/json、multipart/form-data 三种格式(见 f_http/src/MediaTypes.cj),并支持通过 register 注册自定义 MediaType(也可由 Bean 工厂自动注册,f_http/src/MediaTypes.cj)。tryParse 还会截取 ; 之前的媒体类型名进行匹配并基于原字符串重建实例(f_http/src/MediaTypes.cj),因此 application/json; charset=utf-8 这类带参数的 contentType 也能正确解析。


三、FormBuilder:application/x-www-form-urlencoded 表单

FormBuilder 用于构造 URL 编码表单,声明如下:

public class FormBuilder {
    public func add(key: String, value: String): This
    public func set(key: String, value: String): This
    public func remove(key: String): This
    public func get(): HttpResponse
    public func delete(): HttpResponse
    public func put(): HttpResponse
    public func post(): HttpResponse
}

三个参数操作方法的语义:

  • add(key, value):添加一个表单参数;
  • set(key, value):修改参数,若表单内已有同名参数,原参数会被新值覆盖;
  • remove(key):删除指定参数。

从源码实现(httpclient.cj)可以看到,FormBuilder 内部持有创建它的 HttpClient 实例和一个 Form 对象,并针对不同请求方法采用不同编码位置:

private func build(): HttpClient {
    client.url = '${client.url}?${form.toEncodeString()}'
    client
}
public func get(): HttpResponse { return build().get() }
public func delete(): HttpResponse { return build().delete() }
public func put(): HttpResponse { return client.put(form.toEncodeString()) }
public func post(): HttpResponse { return client.post(form.toEncodeString()) }
  • GET / DELETE:表单参数通过 Form.toEncodeString() 编码后拼接到 URL 的查询串(query string)中;
  • PUT / POST:表单参数作为请求体发送(application/x-www-form-urlencoded 语义)。

典型用法:

let resp = HttpClient("https://api.example.com/login")
    .form()
    .add("username", "fountain")
    .set("password", "secret")
    .remove("temp_field")
    .post()

四、MultipartFormDataBuilder:multipart/form-data 文件上传

MultipartFormDataBuilder 用于构造 multipart/form-data 数据格式,多用于文件上传场景。声明如下:

public class MultipartFormDataBuilder {
    public func newPart(): MultipartFileBuilder
    public func put(): Unit
    public func post(): Unit
}

其构造逻辑(httpclient.cj)展示了 fountain 的"约定优于配置"风格——boundary 完全自动生成:

public class MultipartFormDataBuilder {
    private let data = MultipartFormData()
    MultipartFormDataBuilder(private let client: HttpClient){
        client.header('Content-Type', 'multipart/form-data; boundary=${data.boundary}')
    }
    public func newPart(): MultipartFileBuilder { data.newPart() }
    public func put() { client.put(data.input()) }
    public func post() { client.post(data.input()) }
}

创建 builder 时即自动设置带 boundary 的 Content-Type 头(boundary 由 f_http 的 MultipartFormData 生成,格式为 FountainBoundary + 32 位随机字母数字,见 f_http/README.md),调用 newPart() 得到 MultipartFileBuilder 来逐段构造数据,最后 put() / post() 以输入流形式发送整个 multipart 体。

MultipartFileBuilder 由 f_http 模块提供(见 f_http/README.md),常用方法:

public func name(name: String): This                      // 本段数据的名称
public func value(content: Array<Byte>): This             // 本段数据的值
public func value<T>(content: T): This where T <: ToString // 值,转 UTF8 字节
public func file(file: File): This                        // 本段是一个文件
public func file(fileName: String, content: InputStream, size!: Int64 = -1,
                 creationDate!: ?DateTime = None<DateTime>,
                 modificationDate!: ?DateTime = None<DateTime>): This
public func build(): MultipartFormData

文件上传示例:

let resp = HttpClient("https://api.example.com/upload")
    .multipartFormdata()
    .newPart()
    .name("file")
    .file(File("/path/to/report.pdf"))
    .build()
    .post()

五、ExtendHttpResponse:响应体读取与类型转换

模块通过 extend 扩展了仓颉标准库的 HttpResponse(见 f_httpclient/src/ExtendHttpResponse.cj):

public interface ExtendHttpResponse {
    func convert<T>(): ?T where T <: DataFields<T>
}
extend HttpResponse <: ExtendHttpResponse

5.1 字节与文本读取

实际扩展提供的完整成员(ExtendHttpResponse.cj):

public interface ExtendHttpResponse {
    func readToEnd(): Array<Byte>
    func reader(): StringReader<InputStream>
    func reader(charset: Charset): TextReader
    func readEntire(): String
    func readEntire(charset: Charset): String
    func tryParse<T>(): ?T where T <: DataFields<T>
    func convert<T>(): ?T where T <: DataFields<T>{ tryParse<T>() }
    func readJson(): JsonValue
    func readJson(charset: Charset): JsonValue
}
  • readToEnd():读取整个响应体为字节数组。实现上优先利用 bodySize 精确分配缓冲区;若响应没有给出 bodySize,则使用 1024 字节的临时缓冲循环读取(ExtendHttpResponse.cj);
  • readEntire():将字节按 UTF-8 解码为字符串(readToEnd() |> String.unsafeUtf8),另有带 Charset 参数的重载用于其它字符集;
  • reader():返回 StringReader<InputStream>,适合按行或流式读取;带字符集的重载返回 TextReader;
  • readJson():将整个响应体解析为 f_data 的 JsonValue(JsonValue.fromStr(json))。

5.2 按 Content-Type 反序列化:tryParse / convert

tryParse<T>() 是响应反序列化的入口(ExtendHttpResponse.cj):

public func tryParse<T>(): ?T where T <: DataFields<T> {
    let contentType = this.headers.getFirst('Content-Type') ?? 'application/json'
    tryParse<T>(contentType)
}

它读取响应头 Content-Type(缺省按 application/json 处理),再交给 MediaTypes.tryParse(contentType) 解析媒体类型,调用 MediaType.toDataFields<T>(body) 将响应体转换为目标类型;如果响应体没有 bodySize(即无实体内容),则返回 None(ExtendHttpResponse.cj)。convert<T>() 是 tryParse<T>() 的别名。

响应消费示例:

let resp = HttpClient("https://api.example.com/user/1").get()
// 1) 整个响应体作为字符串
let text = resp.readEntire()
// 2) 直接解析为 JSON
let json = resp.readJson()
// 3) 反序列化为 DataFields 类型(如带 @Data 宏的模型类)
let user: ?User = resp.tryParse<User>()

依赖说明:tryParse 依赖 f_data 的 DataFields<T> 数据转换体系与 f_http 的 MediaType/MediaTypes 媒体类型体系,这两个模块的详细设计可分别参见 f_data/README.md 与 f_http/README.md。


六、其他公开 API 速查

以下 API 未在上文逐一展开,按类型分组列出;完整语义见 f_httpclient/src/httpclient.cj 与 f_httpclient/src/ExtendHttpResponse.cj。

HttpClient 补充成员(全部返回 This,支持链式)

方法 语义
enablePush(enable: Bool) 是否启用 HTTP/2 Server Push
headerTableSize(size: UInt32) HTTP/2 头部压缩表大小
initialWindowSize(size: UInt32) HTTP/2 流初始窗口大小
maxConcurrentStreams(size: UInt32) HTTP/2 最大并发流数
maxFrameSize(size: UInt32) HTTP/2 最大帧大小
maxHeaderListSize(size: UInt32) HTTP/2 最大头部列表大小
httpProxy(addr: String) 设置 HTTP 代理地址
httpsProxy(addr: String) 设置 HTTPS 代理地址
noProxy() 关闭代理
logger(logger: Logger) 设置日志记录器

上述 HTTP/2 与代理配置直接委托给底层 ClientBuilder(httpclient.cj),适合需要精细控制协议行为或走代理访问外网的服务端场景。

HttpResponse 扩展成员

方法 语义
readEntire(): String 读取整个响应体为 UTF-8 字符串
readJson(): JsonValue 解析响应体为 JsonValue
readToEnd(): Array<Byte> 读取整个响应体为字节数组
reader(): StringReader<InputStream> 流式读取响应体
tryParse<T>(): ?T(where T <: DataFields<T>) 按 Content-Type 反序列化为泛型类型
convert<T>(): ?T(where T <: DataFields<T>) tryParse 的别名

仓库内真实用例:f_llm 的 HTTP 封装

f_llm 模块内部封装了带认证的 HTTP 调用(f_llm/src/util/http.cj),是 HttpClient 在实际模块中的典型用法:

public func http<T>(url: String, auth: String, callback: (HttpClient) -> T): T {
    let client = HttpClient(url)
    client.header("Authorization", 'Bearer ${auth}')
    client.header("Content-Type", "application/json")
    client.header("Accept", "application/json")
    var tls = TlsClientConfig()
    tls.verifyMode = CertificateVerifyMode.TrustAll
    client.tlsConfig(tls)
    resource(client, callback)
}

它展示了三个要点:① 通过 header 注入 Authorization: Bearer ... 认证信息;② 通过 tlsConfig 设置 TLS 校验模式;③ 利用 HttpClient <: Resource 配合 resource(client, callback) 自动管理生命周期。


七、依赖与使用总结

要使用 f_httpclient,你需要满足以下条件:

  1. 环境:配置 CANGJIE_STDX_DYNAMIC_PATH 指向动态标准库(模块以 --dy-std 方式编译,见 f_httpclient/cjpm.toml);
  2. 依赖:f_httpclient 依赖 f_base、f_data、f_http 与 charset4cj,在 cjpm.toml 中声明 "fountain::f_httpclient" = {path = "../f_httpclient"} 即可(若使用聚合包则依赖 fountain::fountain.httpclient,见 README.md);
  3. 核心能力速览:
    • 链式配置:autoRedirect / poolSize / readTimeout / writeTimeout / tlsConfig / header 等全部返回 This;
    • 四类请求体重载:String / InputStream / Array<Byte> / DataFields<T>(自动媒体类型编码);
    • 表单:form().add().set().remove().post()(GET/DELETE 走查询串,PUT/POST 走请求体);
    • 文件上传:multipartFormdata().newPart().name().file().build().post()(boundary 自动生成);
    • 响应处理:readEntire() / readJson() / readToEnd() / reader() / tryParse<T>()。

从源码结构看,f_httpclient 的设计目标是让开发者以最少样板代码完成 HTTP 调用:连接与请求两个 builder 的分工使配置与发送解耦,MediaTypes + DataFields 的组合让"对象 → 请求体"与"响应体 → 对象"两个方向都做到类型安全,而 Resource 实现则让资源管理与 fountain 的自动初始化、生命周期机制天然契合。

登录后查看全文
fountain