Forest 参数注解

@Query 注解

/**
 * 使用 @Query 注解，可以直接将该注解修饰的参数动态绑定到请求url中
 * 注解的 value 值即代表它在url的Query部分的参数名
 */
@Get("http://localhost:8080/abc?id=0")
String send(@Query("a") String a, @Query("b") String b);


/**
 * 使用 @Query 注解，可以修饰 Map 类型的参数
 * 很自然的，Map 的 Key 将作为 URL 的参数名， Value 将作为 URL 的参数值
 * 这时候 @Query 注解不定义名称
 */
@Get("http://localhost:8080/abc?id=0")
String send1(@Query Map<String, Object> map);


/**
 * @Query 注解也可以修饰自定义类型的对象参数
 * 依据对象类的 Getter 和 Setter 的规则取出属性
 * 其属性名为 URL 参数名，属性值为 URL 参数值
 * 这时候 @Query 注解不定义名称
 */
@Get("http://localhost:8080/abc?id=0")
String send2(@Query UserInfo user);

@JSONQuery 注解

@Get("http://localhost:8080/abc")
String send(@JSONQuery("id") List idList);

@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);

@Body 注解

/**
 * 默认body格式为 application/x-www-form-urlencoded，即以表单形式序列化数据
 */
@Post("http://localhost:8080/user")
String sendPost(@Body("username") String username,  @Body("password") String password);

表单格式

/**
 * contentType属性设置为 application/x-www-form-urlencoded 即为表单格式，
 * 当然不设置的时候默认值也为 application/x-www-form-urlencoded， 也同样是表单格式。
 * 在 @Body 注解的 value 属性中设置的名称为表单项的 key 名，
 * 而注解所修饰的参数值即为表单项的值，它可以为任何类型，不过最终都会转换为字符串进行传输。
 */
@Post(
    url = "http://localhost:8080/user",
    contentType = "application/x-www-form-urlencoded"
)
String sendPost(@Body("key1") String value1,  @Body("key2") Integer value2, @Body("key3") Long value3);

@JSONBody注解修饰对象

/**
 * 被@JSONBody注解修饰的参数会根据其类型被自定解析为JSON字符串
 * 使用@JSONBody注解时可以省略 contentType = "application/json"属性设置
 */
@Post("http://localhost:8080/hello/user")
String helloUser(@JSONBody User user);

@XMLBody注解修饰对象

/**
 * 被@JSONBody注解修饰的参数会根据其类型被自定解析为XML字符串
 * 其修饰的参数类型必须支持JAXB，可以使用JAXB的注解进行修饰
 * 使用@XMLBody注解时可以省略 contentType = "application/xml"属性设置
 */
@Post("http://localhost:8080/hello/user")
String sendXmlMessage(@XMLBody User user);

Protobuf格式

在使用 Protobuf 之前，首先需要有引入 google 的 protobuf 包依赖

@Post("/proto/data")
ProtobufProto.MyData protobufTest2(@ProtobufBody ProtobufProto.MyData myData);

// 调用改方法，会将 myData 数据对象自动转换为 Protobuf 格式字节流
// 并发送到服务端
// @ProtobufBody 在默认请情况下会将 Content-Type 设为
// application/x-protobuf

二进制格式

/**
 * 发送Byte数组类型数据
 */
@Post(
        url = "/upload/${filename}",
        contentType = "application/octet-stream"
)
String sendByteArryr(@Body byte[] body, @Var("filename") String filename);

/**
 * 发送File类型数据
 */
@Post(
    url = "/upload/${filename}",
    contentType = "application/octet-stream"
)
String sendFile(@Body File file, @Var("filename") String filename);

/**
 * 发送输入流类型数据
 */
@Post(
    url = "/upload/${filename}",
    contentType = "application/octet-stream"
)
String sendInputStream(@Body InputStream inputStream, @Var("filename") String filename);

@DataFile注解

/**
 * 用@DataFile注解修饰要上传的参数对象
 * OnProgress参数为监听上传进度的回调函数
 */
@Post(url = "/upload")
Map upload(@DataFile("file") String filePath, OnProgress onProgress);


Map result = myClient.upload("D:\\TestUpload\\xxx.jpg", progress -> {
    System.out.println("total bytes: " + progress.getTotalBytes());   // 文件大小
    System.out.println("current bytes: " + progress.getCurrentBytes());   // 已上传字节数
    System.out.println("progress: " + Math.round(progress.getRate() * 100) + "%");  // 已上传百分比
    if (progress.isDone()) {   // 是否上传完成
        System.out.println("--------   Upload Completed!   --------");
    }
});

@DownloadFile注解

/**
 * 在方法上加上@DownloadFile注解
 * dir属性表示文件下载到哪个目录
 * filename属性表示文件下载成功后以什么名字保存，如果不填，这默认从URL中取得文件名
 * OnProgress参数为监听上传进度的回调函数
 */
@Get(url = "http://localhost:8080/images/xxx.jpg")
@DownloadFile(dir = "${0}", filename = "${1}")
File downloadFile(String dir, String filename, OnProgress onProgress);

File file = myClient.downloadFile("D:\\TestDownload", progress -> {
    System.out.println("total bytes: " + progress.getTotalBytes());   // 文件大小
    System.out.println("current bytes: " + progress.getCurrentBytes());   // 已下载字节数
    System.out.println("progress: " + Math.round(progress.getRate() * 100) + "%");  // 已下载百分比
    if (progress.isDone()) {   // 是否下载完成
        System.out.println("--------   Download Completed!   --------");
    }
});