v1.5.28文档
声明式接口

🍭 请求头

在《构建接口》的例子中，我们已经知道了可以通过@Request注解的headers属性设置一条 HTTP 请求头。

现在我们来看看如何添加多条请求头。

# headers属性

其中headers属性接受的是一个字符串数组，在接受多个请求头信息时以以下形式填入请求头：

{
    "请求头名称1: 请求头值1",
    "请求头名称2: 请求头值2",
    "请求头名称3: 请求头值3",
    ...
 }

1
2
3
4
5
6

其中组数每一项都是一个字符串，每个字符串代表一个请求头。请求头的名称和值用:分割。

具体代码请看如下示例：

public interface MyClient {

    @Request(
            url = "http://localhost:8080/hello/user",
            headers = {
                "Accept-Charset: utf-8",
                "Content-Type: text/plain"
            }
    )
    String multipleHeaders();
}

1
2
3
4
5
6
7
8
9
10
11

该接口调用后所实际产生的 HTTP 请求如下：

GET http://localhost:8080/hello/user
HEADER:
    Accept-Charset: utf-8
    Content-Type: text/plain

如果要每次请求传入不同的请求头内容，可以在headers属性的请求头定义中加入数据绑定。

public interface MyClient {

    @Request(
            url = "http://localhost:8080/hello/user",
            headers = {
                "Accept-Charset: ${encoding}",
                "Content-Type: text/plain"
            }
    )
    String bindingHeader(@Var("encoding") String encoding);
}

1
2
3
4
5
6
7
8
9
10
11

如果调用方代码如下所示：

myClient.bindingHeader("gbk");

这段调用所实际产生的 HTTP 请求如下：

GET http://localhost:8080/hello/user
HEADER:
    Accept-Charset: gbk
    Content-Type: text/plain

想必大家都已经了解通过 headers 属性设置请求头的方法了。不过这种方式虽然直观，但如要没通过参数传入到请求头中就显得比较啰嗦了。

所以Forest还提供了 @Header 注解来帮助您把方法的参数直接绑定到请求体中。


/**
 * 使用 @Header 注解将参数绑定到请求头上
 * @Header 注解的 value 指为请求头的名称，参数值为请求头的值
 * @Header("Accept") String accept将字符串类型参数绑定到请求头 Accept 上
 * @Header("accessToken") String accessToken将字符串类型参数绑定到请求头 accessToken 上
 */
@Post("http://localhost:8080/hello/user?username=foo")
void postUser(@Header("Accept") String accept, @Header("accessToken") String accessToken);

1
2
3
4
5
6
7
8
9
10

如果有很多很多的请求头要通过参数传入，我需要定义很多很多参数吗？当然不用！

/**
 * 使用 @Header 注解可以修饰 Map 类型的参数
 * Map 的 Key 指为请求头的名称，Value 为请求头的值
 * 通过此方式，可以将 Map 中所有的键值对批量地绑定到请求头中
 */
@Post("http://localhost:8080/hello/user?username=foo")
void headHelloUser(@Header Map<String, Object> headerMap);


/**
 * 使用 @Header 注解可以修饰自定义类型的对象参数
 * 依据对象类的 Getter 和 Setter 的规则取出属性
 * 其属性名为 URL 请求头的名称，属性值为请求头的值
 * 以此方式，将一个对象中的所有属性批量地绑定到请求头中
 */
@Post("http://localhost:8080/hello/user?username=foo")
void headHelloUser(@Header MyHeaderInfo headersInfo);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

注意

(1) 需要单个单个定义请求头的时候，@Header注解的value值一定要有，比如 @Header("Content-Type") String contentType
(2) 需要绑定对象的时候，@Header注解的value值一定要空着，比如 @Header MyHeaders headers 或 @Header Map headerMap

帮助我们改善此文档

上次更新: 2023/06/19, 17:37:19

← 🎈 URL 参数 👔 请求体→

🍭 请求头

# headers属性

# @Header 注解