如何在URL中查询API的name字段并结合Retrofit使用该API

一、URL查询name字段的方式 #

• 精确匹配查询：如果API支持按name字段过滤，直接在URL末尾拼接查询参数即可，格式为 ?name=目标名称。例如要查询名为سُورَةُ ٱلْفَاتِحَةِ的条目，URL示例如下：

  https://your-api-domain.com/surahs?name=سُورَةُ ٱلْفَاتِحَةِ
  

  注意：非英文特殊字符需要做URL编码，阿拉伯语字符会被转译为类似%D8%B3%D9%8F%D9%88%D8%B1%D8%A9%D9%8F%20%D9%81%D8%A7%D8%A9%D9%87%D8%A9的格式，大部分HTTP客户端会自动处理编码，无需手动转换。
• 模糊匹配查询（需API支持）：部分API会提供模糊搜索参数，比如name_like或q，示例URL如下：

  https://your-api-domain.com/surahs?name_like=Fatiha
  

  具体参数名需参照API官方文档，无文档时可尝试常见的模糊查询参数名。

二、在Retrofit中集成该API #

1. 添加依赖 #

在app模块的build.gradle（或build.gradle.kts）中引入Retrofit及Gson转换器依赖：

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}

2. 创建数据模型类 #

根据API返回的JSON结构，对应创建实体类：

顶层响应类ApiResponse

data class ApiResponse(
    val code: Int,
    val status: String,
    val data: Data
)

数据容器类Data

data class Data(
    val surahs: List<Surah>
)

章节类Surah

data class Surah(
    val number: Int,
    val name: String,
    val englishName: String,
    val englishNameTranslation: String,
    val revelationType: String,
    val ayahs: List<Ayah>? = null // ayahs字段可根据实际需求扩展Ayah类
)

// 可选：Ayah类示例
data class Ayah(
    // 根据ayahs的实际字段定义，如number、text等
)

若使用Java开发，需添加@SerializedName注解映射字段，示例：

public class Surah {
    @SerializedName("number")
    private int number;
    @SerializedName("name")
    private String name;
    // 其余字段及getter、setter省略
}

3. 定义Retrofit接口 #

创建接口描述API请求规则：

interface QuranApiService {
    // 获取全部章节列表
    @GET("surahs")
    suspend fun getSurahs(): Response<ApiResponse>

    // 根据name字段过滤章节
    @GET("surahs")
    suspend fun getSurahsByName(@Query("name") name: String): Response<ApiResponse>
}

Java版本需将返回类型改为Call<ApiResponse>，去掉suspend关键字：

public interface QuranApiService {
    @GET("surahs")
    Call<ApiResponse> getSurahs();

    @GET("surahs")
    Call<ApiResponse> getSurahsByName(@Query("name") String name);
}

4. 初始化Retrofit实例 #

val retrofit = Retrofit.Builder()
    .baseUrl("https://your-api-domain.com/") // 替换为实际API基础地址
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val quranApiService = retrofit.create(QuranApiService::class.java)

5. 发起请求 #

Kotlin（协程方式）

// 获取全部章节
CoroutineScope(Dispatchers.IO).launch {
    val response = quranApiService.getSurahs()
    if (response.isSuccessful) {
        val surahs = response.body()?.data?.surahs
        // 处理获取到的章节列表
    } else {
        // 处理请求失败逻辑
    }
}

// 根据name查询章节
val targetName = "سُورَةُ ٱلْفَاتِحَةِ"
CoroutineScope(Dispatchers.IO).launch {
    val response = quranApiService.getSurahsByName(targetName)
    if (response.isSuccessful) {
        val filteredSurahs = response.body()?.data?.surahs
        // 处理过滤后的结果
    } else {
        // 处理请求失败逻辑
    }
}

Java（异步回调方式）

quranApiService.getSurahsByName("سُورَةُ ٱلْفَاتِحَةِ")
    .enqueue(new Callback<ApiResponse>() {
        @Override
        public void onResponse(Call<ApiResponse> call, Response<ApiResponse> response) {
            if (response.isSuccessful()) {
                List<Surah> surahs = response.body().getData().getSurahs();
                // 处理查询结果
            }
        }

        @Override
        public void onFailure(Call<ApiResponse> call, Throwable t) {
            // 处理请求错误
        }
    });

内容的提问来源于stack exchange，提问作者Marwan Talal