fountain f_httpclient 实战指南:基于仓颉语言的 HTTP 客户端封装与调用
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,你需要满足以下条件:
- 环境:配置
CANGJIE_STDX_DYNAMIC_PATH指向动态标准库(模块以--dy-std方式编译,见 f_httpclient/cjpm.toml); - 依赖:
f_httpclient依赖f_base、f_data、f_http与charset4cj,在cjpm.toml中声明"fountain::f_httpclient" = {path = "../f_httpclient"}即可(若使用聚合包则依赖fountain::fountain.httpclient,见 README.md); - 核心能力速览:
- 链式配置:
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 的自动初始化、生命周期机制天然契合。