Merge pull request 'v0.2.0' (#21) from dev into master

Reviewed-on: #21

README.md

@@ -1,3 +1,14 @@
 # timi-network
 
 Java 网络操作工具
+
+静态工厂方法按 HTTP 方法命名，支持 `get`、`post`、`put`、`patch`、`delete`、`head` 和 `options`，分别用于读取、创建、替换、部分更新、删除资源、获取响应头和查询支持的请求方法
+
+`CommonRequest`、`JacksonRequest`、`FileRequest` 和 `TimiRequest` 的工厂方法均返回对应类型，`ProgressiveRequest` 的工厂方法额外接收进度回调
+
+```java
+JacksonRequest.put("https://example.com/users/1").body(user).execute();
+JacksonRequest.patch("https://example.com/users/1").body(changes).execute();
+CommonRequest.delete("https://example.com/users/1").execute();
+long length = FileRequest.head("https://example.com/files/1").length();
+```

pom.xml

@@ -6,7 +6,7 @@
 
 	<groupId>com.imyeyu.network</groupId>
 	<artifactId>timi-network</artifactId>
-	<version>0.0.13</version>
+	<version>0.2.0</version>
 	<packaging>jar</packaging>
 
 	<properties>
@@ -106,7 +106,7 @@
 		<dependency>
 			<groupId>com.imyeyu.io</groupId>
 			<artifactId>timi-io</artifactId>
-			<version>0.0.5</version>
+			<version>0.1.0</version>
 		</dependency>
 		<dependency>
 			<groupId>org.apache.httpcomponents.client5</groupId>

src/main/java/com/imyeyu/network/CommonRequest.java

@@ -1,8 +1,12 @@
 package com.imyeyu.network;
 
 import com.imyeyu.java.TimiJava;
+import com.imyeyu.java.bean.CallbackArg;
+import org.apache.hc.client5.http.fluent.ContentResponseHandler;
 import org.apache.hc.client5.http.fluent.Request;
 import org.apache.hc.core5.http.HttpEntity;
+import org.apache.hc.core5.http.HttpResponse;
+import org.apache.hc.core5.http.io.HttpClientResponseHandler;
 import org.apache.hc.core5.util.Timeout;
 
 import java.io.IOException;
@@ -16,6 +20,9 @@ public class CommonRequest {
 
 	protected final Request request;
 
+	/// 响应回调
+	protected CallbackArg<HttpResponse> responseCallback;
+
 	protected CommonRequest(Request request) {
 		this.request = request;
 	}
@@ -32,6 +39,46 @@ public class CommonRequest {
 		return new CommonRequest(Request.post(url));
 	}
 
+	/// 创建 PUT 请求，用于替换资源
+	///
+	/// @param url 请求地址
+	/// @return CommonRequest 请求
+	public static CommonRequest put(String url) {
+		return new CommonRequest(Request.put(url));
+	}
+
+	/// 创建 PATCH 请求，用于部分更新资源
+	///
+	/// @param url 请求地址
+	/// @return CommonRequest 请求
+	public static CommonRequest patch(String url) {
+		return new CommonRequest(Request.patch(url));
+	}
+
+	/// 创建 DELETE 请求，用于删除资源
+	///
+	/// @param url 请求地址
+	/// @return CommonRequest 请求
+	public static CommonRequest delete(String url) {
+		return new CommonRequest(Request.delete(url));
+	}
+
+	/// 创建 HEAD 请求，用于获取响应头
+	///
+	/// @param url 请求地址
+	/// @return CommonRequest 请求
+	public static CommonRequest head(String url) {
+		return new CommonRequest(Request.head(url));
+	}
+
+	/// 创建 OPTIONS 请求，用于查询支持的请求方法
+	///
+	/// @param url 请求地址
+	/// @return CommonRequest 请求
+	public static CommonRequest options(String url) {
+		return new CommonRequest(Request.options(url));
+	}
+
 	public CommonRequest timeout(long ms) {
 		if (0 < ms) {
 			request.connectTimeout(Timeout.ofMilliseconds(ms)).responseTimeout(Timeout.ofMilliseconds(ms));
@@ -54,13 +101,22 @@ public class CommonRequest {
 		return header("Accept-Language", langHeader);
 	}
 
+	/// 设置响应回调，回调在响应体读取前执行
+	///
+	/// @param callback 响应回调，传入 null 表示移除回调
+	/// @return 当前请求
+	public CommonRequest responseCallback(CallbackArg<HttpResponse> callback) {
+		this.responseCallback = callback;
+		return this;
+	}
+
 	public CommonRequest bodyEntity(HttpEntity entity) {
 		request.body(entity);
 		return this;
 	}
 
 	public String asString() throws IOException {
-		return request.execute().returnContent().asString();
+		return handleResponse(response -> new ContentResponseHandler().handleResponse(response).asString());
 	}
 
 	public Number asNumber() throws IOException {
@@ -68,14 +124,29 @@ public class CommonRequest {
 	}
 
 	public byte[] asBytes() throws IOException {
-		return request.execute().returnContent().asBytes();
+		return handleResponse(response -> new ContentResponseHandler().handleResponse(response).asBytes());
 	}
 
 	public InputStream asStream() throws IOException {
-		return request.execute().returnContent().asStream();
+		return handleResponse(response -> new ContentResponseHandler().handleResponse(response).asStream());
 	}
 
 	public void execute() throws IOException {
-		request.execute();
+		handleResponse(response -> null);
+	}
+
+	/// 使用统一入口处理响应，子类的自定义响应处理必须调用此方法
+	///
+	/// @param handler 响应处理器
+	/// @param <T> 返回值类型
+	/// @return 响应处理结果
+	/// @throws IOException 请求或响应处理失败
+	protected <T> T handleResponse(HttpClientResponseHandler<T> handler) throws IOException {
+		return request.execute().handleResponse(response -> {
+			if (responseCallback != null) {
+				responseCallback.handler(response);
+			}
+			return handler.handleResponse(response);
+		});
 	}
 }

src/main/java/com/imyeyu/network/FileRequest.java

@@ -1,6 +1,7 @@
 package com.imyeyu.network;
 
 import com.imyeyu.io.IO;
+import com.imyeyu.java.bean.CallbackArg;
 import org.apache.hc.client5.http.fluent.Request;
 import org.apache.hc.core5.http.Header;
 import org.apache.hc.core5.http.HttpEntity;
@@ -35,6 +36,46 @@ public class FileRequest extends JacksonRequest {
 		return new FileRequest(Request.post(url));
 	}
 
+	/// 创建 PUT 请求，用于替换资源
+	///
+	/// @param url 请求地址
+	/// @return FileRequest 请求
+	public static FileRequest put(String url) {
+		return new FileRequest(Request.put(url));
+	}
+
+	/// 创建 PATCH 请求，用于部分更新资源
+	///
+	/// @param url 请求地址
+	/// @return FileRequest 请求
+	public static FileRequest patch(String url) {
+		return new FileRequest(Request.patch(url));
+	}
+
+	/// 创建 DELETE 请求，用于删除资源
+	///
+	/// @param url 请求地址
+	/// @return FileRequest 请求
+	public static FileRequest delete(String url) {
+		return new FileRequest(Request.delete(url));
+	}
+
+	/// 创建 HEAD 请求，用于获取响应头
+	///
+	/// @param url 请求地址
+	/// @return FileRequest 请求
+	public static FileRequest head(String url) {
+		return new FileRequest(Request.head(url));
+	}
+
+	/// 创建 OPTIONS 请求，用于查询支持的请求方法
+	///
+	/// @param url 请求地址
+	/// @return FileRequest 请求
+	public static FileRequest options(String url) {
+		return new FileRequest(Request.options(url));
+	}
+
 	@Override
 	public FileRequest timeout(long ms) {
 		super.timeout(ms);
@@ -59,6 +100,12 @@ public class FileRequest extends JacksonRequest {
 		return this;
 	}
 
+	@Override
+	public FileRequest responseCallback(CallbackArg<HttpResponse> callback) {
+		super.responseCallback(callback);
+		return this;
+	}
+
 	@Override
 	public FileRequest body(Object object) {
 		super.body(object);
@@ -84,15 +131,16 @@ public class FileRequest extends JacksonRequest {
 	}
 
 	public long length() throws IOException, ProtocolException {
-		HttpResponse response = request.execute().returnResponse();
+		return handleResponse(response -> {
-		final int status = response.getCode();
+			final int status = response.getCode();
-		if (status < 200 || 300 <= status) {
+			if (status < 200 || 300 <= status) {
-			throw new IOException("HTTP error status: " + status);
+				throw new IOException("HTTP error status: " + status);
-		}
+			}
-		final Header contentLengthHeader = response.getHeader("Content-Length");
+			final Header contentLengthHeader = response.getHeader("Content-Length");
-		if (contentLengthHeader == null) {
+			if (contentLengthHeader == null) {
-			throw new IOException("Content-Length header missing");
+				throw new IOException("Content-Length header missing");
-		}
+			}
-		return Long.parseLong(contentLengthHeader.getValue());
+			return Long.parseLong(contentLengthHeader.getValue());
+		});
 	}
 }

src/main/java/com/imyeyu/network/JacksonRequest.java

@@ -8,9 +8,11 @@ import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.imyeyu.java.bean.CallbackArg;
 import org.apache.hc.client5.http.fluent.Request;
 import org.apache.hc.core5.http.ContentType;
 import org.apache.hc.core5.http.HttpEntity;
+import org.apache.hc.core5.http.HttpResponse;
 
 import java.io.IOException;
 import java.lang.reflect.Type;
@@ -29,7 +31,7 @@ public class JacksonRequest extends CommonRequest {
 	static {
 		OBJECT_MAPPER.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
 		OBJECT_MAPPER.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
-		OBJECT_MAPPER.setSerializationInclusion(JsonInclude.Include.NON_NULL);
+		OBJECT_MAPPER.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);
 	}
 
 	private ObjectMapper objectMapper = null;
@@ -80,6 +82,46 @@ public class JacksonRequest extends CommonRequest {
 		return new JacksonRequest(Request.post(url));
 	}
 
+	/// 创建 PUT 请求，用于替换资源
+	///
+	/// @param url 请求地址
+	/// @return JacksonRequest 请求
+	public static JacksonRequest put(String url) {
+		return new JacksonRequest(Request.put(url));
+	}
+
+	/// 创建 PATCH 请求，用于部分更新资源
+	///
+	/// @param url 请求地址
+	/// @return JacksonRequest 请求
+	public static JacksonRequest patch(String url) {
+		return new JacksonRequest(Request.patch(url));
+	}
+
+	/// 创建 DELETE 请求，用于删除资源
+	///
+	/// @param url 请求地址
+	/// @return JacksonRequest 请求
+	public static JacksonRequest delete(String url) {
+		return new JacksonRequest(Request.delete(url));
+	}
+
+	/// 创建 HEAD 请求，用于获取响应头
+	///
+	/// @param url 请求地址
+	/// @return JacksonRequest 请求
+	public static JacksonRequest head(String url) {
+		return new JacksonRequest(Request.head(url));
+	}
+
+	/// 创建 OPTIONS 请求，用于查询支持的请求方法
+	///
+	/// @param url 请求地址
+	/// @return JacksonRequest 请求
+	public static JacksonRequest options(String url) {
+		return new JacksonRequest(Request.options(url));
+	}
+
 	/**
 	 * 指定对象映射器。
 	 *
@@ -115,6 +157,12 @@ public class JacksonRequest extends CommonRequest {
 		return this;
 	}
 
+	@Override
+	public JacksonRequest responseCallback(CallbackArg<HttpResponse> callback) {
+		super.responseCallback(callback);
+		return this;
+	}
+
 	/**
 	 * 设置 JSON 请求体
 	 *

src/main/java/com/imyeyu/network/ProgressiveRequest.java

@@ -2,9 +2,10 @@ package com.imyeyu.network;
 
 import com.imyeyu.io.IO;
 import com.imyeyu.java.TimiJava;
+import com.imyeyu.java.bean.CallbackArg;
 import org.apache.hc.client5.http.fluent.Request;
-import org.apache.hc.client5.http.fluent.Response;
 import org.apache.hc.core5.http.HttpEntity;
+import org.apache.hc.core5.http.HttpResponse;
 import org.apache.hc.core5.http.io.HttpClientResponseHandler;
 import org.apache.hc.core5.http.io.entity.EntityUtils;
 
@@ -42,6 +43,51 @@ public class ProgressiveRequest extends FileRequest {
 		return new ProgressiveRequest(Request.post(url), callback);
 	}
 
+	/// 创建 PUT 请求，用于替换资源
+	///
+	/// @param url 请求地址
+	/// @param callback 进度回调
+	/// @return ProgressiveRequest 请求
+	public static ProgressiveRequest put(String url, ProgressiveCallback callback) {
+		return new ProgressiveRequest(Request.put(url), callback);
+	}
+
+	/// 创建 PATCH 请求，用于部分更新资源
+	///
+	/// @param url 请求地址
+	/// @param callback 进度回调
+	/// @return ProgressiveRequest 请求
+	public static ProgressiveRequest patch(String url, ProgressiveCallback callback) {
+		return new ProgressiveRequest(Request.patch(url), callback);
+	}
+
+	/// 创建 DELETE 请求，用于删除资源
+	///
+	/// @param url 请求地址
+	/// @param callback 进度回调
+	/// @return ProgressiveRequest 请求
+	public static ProgressiveRequest delete(String url, ProgressiveCallback callback) {
+		return new ProgressiveRequest(Request.delete(url), callback);
+	}
+
+	/// 创建 HEAD 请求，用于获取响应头
+	///
+	/// @param url 请求地址
+	/// @param callback 进度回调
+	/// @return ProgressiveRequest 请求
+	public static ProgressiveRequest head(String url, ProgressiveCallback callback) {
+		return new ProgressiveRequest(Request.head(url), callback);
+	}
+
+	/// 创建 OPTIONS 请求，用于查询支持的请求方法
+	///
+	/// @param url 请求地址
+	/// @param callback 进度回调
+	/// @return ProgressiveRequest 请求
+	public static ProgressiveRequest options(String url, ProgressiveCallback callback) {
+		return new ProgressiveRequest(Request.options(url), callback);
+	}
+
 	@Override
 	public ProgressiveRequest timeout(long ms) {
 		super.timeout(ms);
@@ -66,6 +112,12 @@ public class ProgressiveRequest extends FileRequest {
 		return this;
 	}
 
+	@Override
+	public ProgressiveRequest responseCallback(CallbackArg<HttpResponse> callback) {
+		super.responseCallback(callback);
+		return this;
+	}
+
 	@Override
 	public ProgressiveRequest body(Object object) {
 		super.body(object);
@@ -80,12 +132,12 @@ public class ProgressiveRequest extends FileRequest {
 
 	@Override
 	public void toFile(Path outputPath) throws IOException, NoPermissionException {
-		processResponse(request.execute(), IO.getOutputStream(outputPath.toFile()));
+		processResponse(IO.getOutputStream(outputPath.toFile()));
 	}
 
 	@Override
 	public void toFile(File file) throws IOException, NoPermissionException {
-		processResponse(request.execute(), IO.getOutputStream(file));
+		processResponse(IO.getOutputStream(file));
 	}
 
 	@Override
@@ -96,17 +148,17 @@ public class ProgressiveRequest extends FileRequest {
 	@Override
 	public byte[] asBytes() throws IOException {
 		ByteArrayOutputStream os = new ByteArrayOutputStream();
-		processResponse(request.execute(), os);
+		processResponse(os);
 		return os.toByteArray();
 	}
 
-	private void processResponse(Response response, OutputStream os) throws IOException {
+	private void processResponse(OutputStream os) throws IOException {
-		response.handleResponse((HttpClientResponseHandler<Void>) resp -> {
+		handleResponse((HttpClientResponseHandler<Void>) response -> {
-			HttpEntity entity = resp.getEntity();
+			HttpEntity entity = response.getEntity();
 			if (entity == null) {
 				throw new IOException("not found response entity");
 			}
-			int code = resp.getCode();
+			int code = response.getCode();
 			if (400 <= code) {
 				throw new IOException("response error: %s".formatted(code));
 			}

src/main/java/com/imyeyu/network/TimiRequest.java

@@ -2,9 +2,11 @@ package com.imyeyu.network;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.JavaType;
-import com.imyeyu.java.bean.timi.TimiResponse;
+import com.imyeyu.java.bean.CallbackArg;
+import com.imyeyu.java.bean.Response;
 import org.apache.hc.client5.http.fluent.Request;
 import org.apache.hc.core5.http.HttpEntity;
+import org.apache.hc.core5.http.HttpResponse;
 
 import java.io.IOException;
 import java.lang.reflect.Type;
@@ -31,6 +33,46 @@ public class TimiRequest extends JacksonRequest {
 		return new TimiRequest(Request.post(url));
 	}
 
+	/// 创建 PUT 请求，用于替换资源
+	///
+	/// @param url 请求地址
+	/// @return TimiRequest 请求
+	public static TimiRequest put(String url) {
+		return new TimiRequest(Request.put(url));
+	}
+
+	/// 创建 PATCH 请求，用于部分更新资源
+	///
+	/// @param url 请求地址
+	/// @return TimiRequest 请求
+	public static TimiRequest patch(String url) {
+		return new TimiRequest(Request.patch(url));
+	}
+
+	/// 创建 DELETE 请求，用于删除资源
+	///
+	/// @param url 请求地址
+	/// @return TimiRequest 请求
+	public static TimiRequest delete(String url) {
+		return new TimiRequest(Request.delete(url));
+	}
+
+	/// 创建 HEAD 请求，用于获取响应头
+	///
+	/// @param url 请求地址
+	/// @return TimiRequest 请求
+	public static TimiRequest head(String url) {
+		return new TimiRequest(Request.head(url));
+	}
+
+	/// 创建 OPTIONS 请求，用于查询支持的请求方法
+	///
+	/// @param url 请求地址
+	/// @return TimiRequest 请求
+	public static TimiRequest options(String url) {
+		return new TimiRequest(Request.options(url));
+	}
+
 	@Override
 	public TimiRequest timeout(long ms) {
 		super.timeout(ms);
@@ -55,6 +97,12 @@ public class TimiRequest extends JacksonRequest {
 		return this;
 	}
 
+	@Override
+	public TimiRequest responseCallback(CallbackArg<HttpResponse> callback) {
+		super.responseCallback(callback);
+		return this;
+	}
+
 	@Override
 	public TimiRequest body(Object object) {
 		super.body(object);
@@ -86,7 +134,7 @@ public class TimiRequest extends JacksonRequest {
 	 * @throws IOException 读取或解析失败
 	 */
 	public <T> T resultAs(Class<T> clazz) throws IOException {
-		TimiResponse<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(clazz));
+		Response<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(clazz));
 		if (resp.isFail()) {
 			throw resp.toException();
 		}
@@ -102,7 +150,7 @@ public class TimiRequest extends JacksonRequest {
 	 * @throws IOException 读取或解析失败
 	 */
 	public <T> T resultAs(TypeReference<T> typeReference) throws IOException {
-		TimiResponse<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(typeReference));
+		Response<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(typeReference));
 		if (resp.isFail()) {
 			throw resp.toException();
 		}
@@ -118,7 +166,7 @@ public class TimiRequest extends JacksonRequest {
 	 * @throws IOException 读取或解析失败
 	 */
 	public <T> T resultAs(Type type) throws IOException {
-		TimiResponse<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(type));
+		Response<T> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(type));
 		if (resp.isFail()) {
 			throw resp.toException();
 		}
@@ -127,7 +175,7 @@ public class TimiRequest extends JacksonRequest {
 
 	@Override
 	public void execute() throws IOException {
-		TimiResponse<?> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(Object.class));
+		Response<?> resp = getObjectMapper().treeToValue(asJsonObject(), timiResponseType(Object.class));
 		if (resp.isFail()) {
 			throw resp.toException();
 		}
@@ -140,7 +188,7 @@ public class TimiRequest extends JacksonRequest {
 	 * @return Jackson 类型
 	 */
 	protected JavaType timiResponseType(Class<?> clazz) {
-		return getObjectMapper().getTypeFactory().constructParametricType(TimiResponse.class, clazz);
+		return getObjectMapper().getTypeFactory().constructParametricType(Response.class, clazz);
 	}
 
 	/**
@@ -150,7 +198,7 @@ public class TimiRequest extends JacksonRequest {
 	 * @return Jackson 类型
 	 */
 	protected JavaType timiResponseType(TypeReference<?> typeReference) {
-		return getObjectMapper().getTypeFactory().constructParametricType(TimiResponse.class, getObjectMapper().constructType(typeReference));
+		return getObjectMapper().getTypeFactory().constructParametricType(Response.class, getObjectMapper().constructType(typeReference));
 	}
 
 	/**
@@ -160,6 +208,6 @@ public class TimiRequest extends JacksonRequest {
 	 * @return Jackson 类型
 	 */
 	protected JavaType timiResponseType(Type type) {
-		return getObjectMapper().getTypeFactory().constructParametricType(TimiResponse.class, getObjectMapper().constructType(type));
+		return getObjectMapper().getTypeFactory().constructParametricType(Response.class, getObjectMapper().constructType(type));
 	}
 }

src/test/java/com/imyeyu/network/test/ProgressRequestTest.java

@@ -28,7 +28,7 @@ public class ProgressRequestTest {
 
 	@Test
 	public void testLength() throws Exception {
-		long length = FileRequest.wrap(Request.head(URL2)).length();
+		long length = FileRequest.head(URL2).length();
 		System.out.println(IOSize.format(length));
 	}