本教程详细阐述了如何在android应用中使用retrofit框架发送包含html标签的json数据。通过利用retrofit的json转换器（如gson），开发者可以轻松地将java字符串对象（即使包含特殊html字符）序列化为json请求体，无需手动进行字符转义。文章将提供数据模型定义、api接口设计、retrofit客户端配置及完整的请求发送示例，并强调了相关注意事项，确保数据传输的正确性和安全性。
在Android应用开发中，通过网络API发送数据是常见的需求。有时，我们需要在请求体中包含带有HTML标签的字符串，例如富文本编辑器生成的HTML内容。Retrofit作为流行的HTTP客户端库，结合JSON转换器，能够非常便捷地处理这类需求。本文将详细介绍如何在Retrofit 2.x中实现这一功能。
Retrofit处理HTML字符串的原理
JSON标准允许字符串包含任何Unicode字符。当字符串中包含特殊字符，如双引号（"）、反斜杠（\）、换行符（\n）、回车符（\r）、制表符（\t）以及HTML相关的特殊字符（如<、>、&）时，JSON转换器（如Gson或Moshi）会自动对其进行转义处理。例如，<会被转义为\u003c，>会被转义为\u003e。这种自动转义机制确保了JSON数据的有效性和传输的安全性，同时避免了手动处理字符转义的繁琐。
这意味着，当我们将一个包含HTML标签的Java String对象作为JSON字段发送时，Retrofit配合其配置的JSON转换器会自动将其正确地序列化为JSON字符串，并在传输过程中完成必要的转义。
构建请求数据模型
首先，我们需要定义一个Java对象（POJO），其结构与您希望发送的JSON payload相匹配。根据提供的示例，JSON结构包含一个名为text的字符串字段和一个名为users的字符串列表字段。
立即学习“前端免费学习笔记（深入）”；
{
"text": "<p>ffsdsdf <span class=\"mention\" ...>...</span> </p>",
"users": ["12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a"]
}对应的Java数据模型可以这样定义：
import com.google.gson.annotations.SerializedName;
import java.util.List;
public class PostPayload {
@SerializedName("text")
private String text;
@SerializedName("users")
private List<String> users;
public PostPayload(String text, List<String> users) {
this.text = text;
this.users = users;
}
// Getters and Setters (省略部分代码，实际开发中建议添加)
public String getText() {
return text;
}
public void setText(String text) {
this.text = text;
}
public List<String> getUsers() {
return users;
}
public void setUsers(List<String> users) {
this.users = users;
}
@Override
public String toString() {
return "PostPayload{" +
"text='" + text + '\'' +
", users=" + users +
'}';
}
}说明：
- @SerializedName注解是Gson库提供的，用于指定Java字段与JSON字段之间的映射关系。即使字段名相同，使用它也是一个良好的习惯，可以增加代码的健壮性。
- text字段直接使用String类型来存储HTML内容。
- users字段使用List<String>来存储用户ID列表。
定义Retrofit服务接口
接下来，我们需要定义一个Retrofit服务接口，用于声明HTTP请求方法。由于我们要发送数据，应使用@POST注解，并将前面定义的PostPayload对象作为请求体（@Body）发送。
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.POST;
public interface ApiService {
/**
* 发送包含HTML内容的JSON请求
* @param payload 包含HTML文本和用户列表的请求体
* @return 返回一个Call对象，用于执行异步或同步请求
*/
@POST("your_endpoint_path") // 替换为您的实际API端点路径
Call<ApiResponse> postHtmlContent(@Body PostPayload payload);
}说明：
- @POST("your_endpoint_path")：指定这是一个POST请求，并定义了API的相对路径。
- @Body PostPayload payload：指示Retrofit将payload对象序列化为JSON，并将其作为HTTP请求体发送。
- Call<ApiResponse>：定义了API调用的返回类型。ApiResponse是一个自定义的响应数据模型，您需要根据实际API的响应结构来定义它。例如：
// 示例响应数据模型
public class ApiResponse {
@SerializedName("status")
private String status;
@SerializedName("message")
private String message;
// Getters and Setters
public String getStatus() { return status; }
public void setStatus(String status) { this.status = status; }
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
@Override
public String toString() {
return "ApiResponse{" +
"status='" + status + '\'' +
", message='" + message + '\'' +
'}';
}
}初始化Retrofit客户端
在使用ApiService之前，您需要构建一个Retrofit实例。这通常涉及设置基础URL和添加一个JSON转换器（如GsonConverterFactory）。
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;
import okhttp3.OkHttpClient;
import okhttp3.logging.HttpLoggingInterceptor;
import java.util.concurrent.TimeUnit;
public class RetrofitClient {
private static Retrofit retrofit;
private static final String BASE_URL = "http://your.base.url/"; // 替换为您的API基础URL
public static Retrofit getRetrofitInstance() {
if (retrofit == null) {
// 可选：添加HttpLoggingInterceptor用于调试，查看请求和响应日志
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);
OkHttpClient httpClient = new OkHttpClient.Builder()
.addInterceptor(logging) // 添加日志拦截器
.connectTimeout(30, TimeUnit.SECONDS) // 连接超时
.readTimeout(30, TimeUnit.SECONDS) // 读取超时
.build();
retrofit = new Retrofit.Builder()
.baseUrl(BASE_URL)
.addConverterFactory(GsonConverterFactory.create()) // 使用Gson作为JSON转换器
.client(httpClient) // 设置自定义的OkHttpClient
.build();
}
return retrofit;
}
public static ApiService getApiService() {
return getRetrofitInstance().create(ApiService.class);
}
}说明：
- GsonConverterFactory.create()：这是关键一步，它告诉Retrofit使用Gson库来处理Java对象与JSON之间的序列化和反序列化。Gson会自动处理字符串中的特殊字符转义。
- HttpLoggingInterceptor：这是一个可选的OkHttp拦截器，用于在Logcat中打印HTTP请求和响应的详细信息，非常有助于调试。
发送请求
有了数据模型、服务接口和Retrofit客户端，现在就可以构造数据并发送请求了。
import java.util.Arrays;
import java.util.List;
import retrofit2.Call;
import retrofit2.Callback;
import retrofit2.Response;
public class MainActivity { // 假设在某个Activity或Presenter中执行
public void sendHtmlContent() {
// 1. 准备包含HTML内容的字符串和用户列表
String htmlContent = "<p>这是一个包含<b>粗体</b>和<i>斜体</i>文字的HTML段落。" +
"<span class=\"mention\" data-id=\"user123\">@用户A</span> " +
"以及一个链接：<a href=\"https://example.com\">示例链接</a>。</p>";
List<String> users = Arrays.asList("12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a", "another_user_id");
// 2. 创建请求数据模型实例
PostPayload payload = new PostPayload(htmlContent, users);
// 3. 获取ApiService实例
ApiService apiService = RetrofitClient.getApiService();
// 4. 发送异步请求
Call<ApiResponse> call = apiService.postHtmlContent(payload);
call.enqueue(new Callback<ApiResponse>() {
@Override
public void onResponse(Call<ApiResponse> call, Response<ApiResponse> response) {
if (response.isSuccessful() && response.body() != null) {
// 请求成功，处理API响应
ApiResponse apiResponse = response.body();
System.out.println("API请求成功，状态: " + apiResponse.getStatus() + ", 消息: " + apiResponse.getMessage());
// 可以在这里更新UI或执行其他逻辑
} else {
// 请求失败，处理错误
System.err.println("API请求失败，错误码: " + response.code() + ", 错误信息: " + response.message());
try {
if (response.errorBody() != null) {
System.err.println("错误体: " + response.errorBody().string());
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
@Override
public void onFailure(Call<ApiResponse> call, Throwable t) {
// 网络请求失败（例如无网络连接、DNS解析失败等）
System.err.println("网络请求失败: " + t.getMessage());
t.printStackTrace();
}
});
}
}注意事项
- Retrofit版本兼容性：本教程基于Retrofit 2.x版本。在Retrofit 1.x中，可能需要使用TypedString和@FormUrlEncoded或@Multipart等注解来发送非标准JSON格式的数据，但对于JSON body，Retrofit 2.x的@Body结合转换器是更现代和推荐的做法。原始问题中提到的@EncodedPath通常用于URL路径段的编码，而非请求体字段。
- JSON自动转义：Retrofit配合Gson（或其他JSON转换器）会自动处理HTML特殊字符（如<、>、&、"等）的JSON转义。您无需手动进行StringEscapeUtils.escapeHtml4()之类的操作。服务器端接收到的将是经过JSON转义的字符串，服务器端的JSON解析器会将其还原为原始的HTML字符串。
- 服务器端解析：确保您的后端API能够正确接收和解析包含HTML字符串的JSON数据。大多数现代Web框架的JSON解析器都能正确处理这种转义。
- 安全性（XSS防护）：如果这些HTML内容最终会在客户端（如WebView或TextView）中显示，强烈建议在显示前进行HTML净化（Sanitization），以防止跨站脚本（XSS）攻击。即使数据来自“可信”来源，也应始终进行净化处理。
- 错误处理：在实际应用中，务必对onResponse和onFailure方法进行健壮的错误处理，包括网络错误、HTTP错误码、服务器返回的业务逻辑错误等。
总结
在Android Retrofit中发送包含HTML标签的JSON数据是一个相对直接的任务。通过定义清晰的数据模型、利用Retrofit的@POST和@Body注解，并配置一个合适的JSON转换器（如Gson），Retrofit会自动处理所有必要的序列化和字符转义工作。这使得开发者能够专注于业务逻辑，而无需担心底层的数据格式化细节。遵循上述步骤和注意事项，您可以高效且安全地在您的Android应用中实现这一功能。
