本教程详细阐述了如何在Android应用中使用Retrofit正确地将HTML内容作为字符串嵌入JSON请求体并发送。文章涵盖了请求体数据模型的定义、Retrofit接口的配置，以及通过JSON转换器确保HTML字符串的正确序列化与传输，从而有效处理包含特殊字符的富文本数据。
1. 理解Retrofit与HTML字符串传输的原理
在使用Retrofit进行网络请求时，发送包含HTML标签的字符串作为JSON payload的一部分是一个常见需求，例如在发送富文本内容或带有特定标记的用户评论时。核心原理在于，HTML标签本身在JSON中只是普通的字符串字符。Retrofit结合其配置的JSON转换器（如Gson或Moshi），能够将Java/Kotlin对象自动序列化为JSON字符串。当对象的某个字段是String类型，且其值包含HTML标签时，转换器会负责将这些HTML字符正确地编码为JSON字符串的一部分，包括对双引号、反斜杠等特殊字符进行转义，确保生成的JSON是有效的。
例如，原始的JSON payload可能如下所示：
{
"text": "<p>ffsdsdf <span class=\"mention\" data-index=\"0\" data-denotation-char=\"@\" data-id=\"12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a\" data-value=\"Vendor 3 company Vendor\"><span contenteditable=\"false\"><span class=\"ql-mention-denotation-char\">@</span>Vendor 3 company Vendor</span></span> </p>",
"users": ["12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a"]
}这里的text字段的值是一个包含HTML标签的字符串。Retrofit的任务就是确保这个字符串能够完整且正确地被封装到JSON中并发送出去。
立即学习“前端免费学习笔记（深入）”；
2. 定义请求体的数据模型 (POJO)
首先，我们需要创建一个Java或Kotlin类来表示我们的请求体结构。这个类应该与你期望发送的JSON结构相匹配。
Java示例：
import com.google.gson.annotations.SerializedName;
import java.util.List;
public class PostHtmlRequest {
@SerializedName("text")
private String text;
@SerializedName("users")
private List<String> users;
public PostHtmlRequest(String text, List<String> users) {
this.text = text;
this.users = users;
}
// Getters and Setters (或使用 Lombok 简化)
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;
}
}Kotlin示例：
import com.google.gson.annotations.SerializedName
data class PostHtmlRequest(
@SerializedName("text")
val text: String,
@SerializedName("users")
val users: List<String>
)3. 配置Retrofit接口
接下来，定义一个Retrofit服务接口，用于声明API端点和请求方法。对于POST请求，我们使用@POST注解，并将我们定义的数据模型作为@Body参数传递。
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.POST;
public interface ApiService {
@POST("your_endpoint_path") // 替换为你的实际API端点路径
Call<ApiResponse> postHtmlContent(@Body PostHtmlRequest request);
// ApiResponse是你期望从服务器接收到的响应数据模型
}这里的ApiResponse是你期望从服务器接收到的响应数据模型，你需要根据实际情况定义它。
4. 构建Retrofit客户端
为了使Retrofit能够正确地将PostHtmlRequest对象序列化为JSON，并处理HTML字符串，你需要配置一个JSON转换器。通常，我们使用GsonConverterFactory或MoshiConverterFactory。
示例：使用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 = null;
private static final String BASE_URL = "https://api.example.com/"; // 替换为你的API基础URL
public static ApiService getApiService() {
if (retrofit == null) {
// 可选：添加HttpLoggingInterceptor用于调试，查看请求和响应日志
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);
OkHttpClient client = new OkHttpClient.Builder()
.addInterceptor(logging) // 添加日志拦截器
.connectTimeout(30, TimeUnit.SECONDS) // 连接超时
.readTimeout(30, TimeUnit.SECONDS) // 读取超时
.writeTimeout(30, TimeUnit.SECONDS) // 写入超时
.build();
retrofit = new Retrofit.Builder()
.baseUrl(BASE_URL)
.addConverterFactory(GsonConverterFactory.create()) // 关键：添加Gson转换器
.client(client)
.build();
}
return retrofit.create(ApiService.class);
}
}Gradle依赖 (build.gradle): 为了使用Retrofit和Gson，请确保在你的build.gradle文件中添加以下依赖：
dependencies {
// Retrofit
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
// Gson Converter
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
// OkHttp Logging Interceptor (可选，用于调试)
implementation 'com.squareup.okhttp3:logging-interceptor:4.9.0'
}5. 发送API请求
现在，你可以实例化PostHtmlRequest对象，填充HTML字符串和其他数据，然后通过Retrofit服务接口发送请求。
import java.util.Arrays;
import java.util.List;
public class MainActivity extends AppCompatActivity { // 假设在Activity中调用
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 模拟HTML内容
String htmlContent = "<p>这是一个包含<b>粗体</b>和<i>斜体</i>文字的HTML字符串。</p>" +
"<span class=\"highlight\">一些高亮内容</span>";
// 模拟用户ID列表
List<String> userIds = Arrays.asList("user123", "user456");
// 创建请求体对象
PostHtmlRequest request = new PostHtmlRequest(htmlContent, userIds);
// 获取ApiService实例
ApiService apiService = RetrofitClient.getApiService();
// 发送异步请求
apiService.postHtmlContent(request).enqueue(new Callback<ApiResponse>() {
@Override
public void onResponse(Call<ApiResponse> call, Response<ApiResponse> response) {
if (response.isSuccessful() && response.body() != null) {
// 请求成功，处理响应数据
Log.d("API_CALL", "Success: " + response.body().toString());
// 例如：显示成功消息或更新UI
} else {
// 请求失败，处理错误
try {
Log.e("API_CALL", "Error: " + response.code() + " - " + response.errorBody().string());
} catch (IOException e) {
e.printStackTrace();
}
}
}
@Override
public void onFailure(Call<ApiResponse> call, Throwable t) {
// 网络错误或请求取消
Log.e("API_CALL", "Failure: " + t.getMessage());
}
});
}
}6. 注意事项与总结
- JSON转换器是关键： Retrofit本身不处理JSON序列化/反序列化。GsonConverterFactory或MoshiConverterFactory等转换器负责将Java/Kotlin对象转换为JSON字符串，并在此过程中正确处理String类型字段中的HTML字符转义。
- HTML字符转义： 当HTML字符串被序列化为JSON时，JSON规范要求对某些特殊字符（如双引号"、反斜杠\、换行符\n等）进行转义。例如，"会被转义为\"。这是由JSON转换器自动完成的，你无需手动处理。
- 服务器端解析： 服务器端接收到JSON请求后，需要正确地解析JSON，并从对应的字段中提取出HTML字符串。通常，服务器端的JSON库也会自动处理这些转义字符，还原出原始的HTML字符串。
- 安全性（XSS）： 如果你正在发送用户输入的HTML内容，并且这些内容最终会在其他用户的界面上显示，务必在显示之前进行严格的HTML净化（Sanitization），以防止跨站脚本攻击（XSS）。直接将未经净化的用户输入HTML渲染到网页或应用中是非常危险的。
- Retrofit版本： 本教程的代码示例基于Retrofit 2.x版本。如果你使用的是早期版本，API可能有所不同。
通过以上步骤，你可以轻松地在Android应用中使用Retrofit发送包含HTML字符串的POST请求。核心在于正确定义数据模型和配置JSON转换器，让Retrofit自动处理复杂的序列化过程。
