本教程详细阐述了如何在Android应用中使用Retrofit框架发送包含HTML标签的JSON字符串作为请求体。核心在于利用Retrofit的JSON转换器（如Gson）自动处理字符串序列化，无需特殊编码，确保HTML内容能作为标准的JSON字符串安全地传输到服务器。文章将涵盖数据模型定义、Retrofit接口配置及实际调用示例。
在Android开发中，通过Retrofit向后端API发送数据是常见的操作。有时，我们需要在JSON请求体中包含HTML标签作为字符串内容，例如富文本编辑器生成的HTML片段。许多开发者可能会认为这需要特殊的编码处理，但实际上，Retrofit配合合适的JSON转换器（如Gson或Moshi）能够非常优雅地处理这种情况，将HTML字符串视为普通字符串进行序列化。
1. 理解核心机制：JSON字符串与HTML内容
JSON（JavaScript Object Notation）规范明确指出，字符串值可以包含任何Unicode字符，除了双引号、反斜杠以及一些控制字符（如换行符、回车符、制表符等），这些特殊字符需要通过反斜杠进行转义。HTML标签本身（如<p>, <span>）并不属于JSON需要特殊转义的字符范畴。因此，当我们将一个包含HTML标签的Java/Kotlin String 对象传递给Retrofit时，JSON转换器会将其原样序列化为JSON字符串，并在必要时对内部的JSON特殊字符进行转义。
例如，一个Java/Kotlin字符串 "<p>Hello <b>World</b>!</p>" 经过JSON序列化后，在JSON请求体中会呈现为 "<p>Hello <b>World</b>!</p>"。如果字符串中包含双引号，如 "<a href="#">Link</a>"，则会序列化为 "<a href=\"#\">Link</a>"，这是JSON标准转义行为，与HTML本身无关。
立即学习“前端免费学习笔记（深入）”；
2. Retrofit环境配置
首先，确保你的项目中已添加Retrofit及其JSON转换器依赖。这里以Gson为例：
// build.gradle (app module)
dependencies {
// Retrofit core
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
// Gson converter for Retrofit
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
// OkHttp (Retrofit's underlying HTTP client)
implementation 'com.squareup.okhttp3:okhttp:4.9.0'
implementation 'com.squareup.okhttp3:logging-interceptor:4.9.0' // For logging requests/responses
}3. 定义请求体的数据模型 (POJO)
为了发送结构化的JSON数据，我们需要定义一个数据类（POJO - Plain Old Java Object 或 Kotlin Data Class）来表示请求体。这个数据类中的HTML内容字段应直接定义为 String 类型。
假设我们的目标JSON请求体如下：
{
"text": "<p>ffsdsdf <span class="mention" data-id="...">@Vendor</span></p>",
"users": ["12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a"]
}对应的Kotlin数据类可以这样定义：
// data/PostRequest.kt
package com.example.myapp.data
import com.google.gson.annotations.SerializedName
data class PostRequest(
@SerializedName("text")
val text: String,
@SerializedName("users")
val users: List<String>
)4. 创建Retrofit服务接口
定义一个Retrofit接口，其中包含用于发送POST请求的方法。使用 @POST 注解指定API路径，并使用 @Body 注解将我们定义的数据模型作为请求体发送。
// api/MyApiService.kt
package com.example.myapp.api
import com.example.myapp.data.PostRequest
import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.POST
interface MyApiService {
@POST("your/api/endpoint") // 替换为你的实际API端点
suspend fun postHtmlContent(@Body request: PostRequest): Response<Void> // 假设服务器返回空响应或一个通用成功响应
}5. 构建Retrofit实例并执行请求
在你的应用组件（如Activity、Fragment或ViewModel）中，你需要构建Retrofit实例，创建服务接口的实现，然后调用其方法来发送请求。
// client/RetrofitClient.kt
package com.example.myapp.client
import com.example.myapp.api.MyApiService
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import java.util.concurrent.TimeUnit
object RetrofitClient {
private const val BASE_URL = "https://your.api.base.url/" // 替换为你的API基础URL
private val loggingInterceptor = HttpLoggingInterceptor().apply {
level = HttpLoggingInterceptor.Level.BODY // 打印请求和响应体
}
private val okHttpClient = OkHttpClient.Builder()
.addInterceptor(loggingInterceptor)
.connectTimeout(30, TimeUnit.SECONDS)
.readTimeout(30, TimeUnit.SECONDS)
.writeTimeout(30, TimeUnit.SECONDS)
.build()
val apiService: MyApiService by lazy {
Retrofit.Builder()
.baseUrl(BASE_URL)
.addConverterFactory(GsonConverterFactory.create())
.client(okHttpClient)
.build()
.create(MyApiService::class.java)
}
}现在，你可以在应用中调用 apiService 来发送请求：
// Example usage in an Activity or ViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.example.myapp.client.RetrofitClient
import com.example.myapp.data.PostRequest
import kotlinx.coroutines.launch
class MyViewModel : ViewModel() {
fun sendContentWithHtml() {
viewModelScope.launch {
val htmlContent = "<p>这是一个包含<b>粗体</b>和<i>斜体</i>文字的HTML片段。</p>" +
"<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>"
val users = listOf("12fe9af4-e2d6-47cb-9601-64c7a1fe9c4a")
val requestBody = PostRequest(text = htmlContent, users = users)
try {
val response = RetrofitClient.apiService.postHtmlContent(requestBody)
if (response.isSuccessful) {
println("HTML内容发送成功！")
} else {
println("发送失败: ${response.code()} - ${response.errorBody()?.string()}")
}
} catch (e: Exception) {
println("请求发生异常: ${e.message}")
}
}
}
}6. 注意事项与总结
- JSON转换器的选择和配置： 确保你选择了并正确配置了JSON转换器（如GsonConverterFactory）。它是将Kotlin/Java对象转换为JSON字符串的关键。
- @Body 注解： 对于发送请求体，务必使用 @Body 注解，它告诉Retrofit将参数对象序列化为HTTP请求体。
- @EncodedPath 的误用： 原始问题中可能提到了 @EncodedPath。请注意，@EncodedPath 用于对URL路径段进行编码，例如 GET /users/{id} 中的 {id}。它不适用于请求体中的字段。在请求体中，HTML字符串会由JSON转换器作为普通字符串处理。
- 服务器端解析： 确保你的后端API能够正确接收并解析包含HTML标签的JSON字符串。通常，这只是一个标准的JSON解析过程，后端会获取到一个普通的字符串，其内容恰好是HTML。如果后端需要对HTML内容进行进一步处理（如存储、显示），则由后端逻辑负责。
- 安全性（XSS）： 如果HTML内容是用户输入的，在服务器端显示或处理时，务必进行适当的HTML清理和XSS防护，以防止跨站脚本攻击。这与Retrofit的发送机制无关，但对于处理用户生成HTML的应用至关重要。
- TypedString (Retrofit 1.x 遗留)： 如果你在旧项目中遇到 TypedString，请注意这是Retrofit 1.x 的概念，在Retrofit 2.x 中已被淘汰，不应再使用。
总结： 在Android Retrofit中发送包含HTML标签的JSON字符串请求，并不需要特殊的编码或处理。核心在于定义一个匹配JSON结构的POJO，并将HTML内容字段声明为 String 类型。Retrofit配合JSON转换器（如Gson）会负责将这些字符串正确地序列化到JSON请求体中。遵循标准的Retrofit实践即可轻松实现。
