1. 为什么分页这件事值得从工程配置阶段就认真对待Android 的 Paging library 是一套帮你在 RecyclerView 里“按需加载数据”的官方组件它把数据切成小块、异步拉取、自动刷新适合列表数据量大、又不想一次性全塞进内存的场景。很多同学第一次接触它注意力都放在PagedListAdapter和DiffUtil上结果项目跑不起来回头一查发现是依赖版本对不上、数据源工厂没接好、或者网络层 Key 管理混乱导致请求直接 401。我这次想换个角度不从 UI 讲起而是从工程配置切入把 Paging 的依赖骨架搭好同时把网络请求这一层用 TaoToken 统一 Key 通道接进来。这样做的原因是分页链路里最容易出问题的往往不是分页算法本身而是“数据从哪来、用什么凭证去拿”。把这两件事在配置阶段就理顺后面写DataSource会顺很多。这篇是系列第一篇目标很明确交付一份可复制的build.gradle依赖片段、一份 TaoToken 接入配置骨架、以及一个能验证分页数据源初始化是否成功的最小动作。你跟着做完应该能看到日志里打出第一页数据而不是对着空白列表发呆。适合谁看已经会写 RecyclerView Adapter、对 ViewModel 和协程有基本了解、但还没系统跑通过 Paging 的 Android 开发者。如果你完全没接触过 Paging也没关系我会把每一步的意图讲清楚。2. TaoToken 前置准备把统一 Key 和 API 通道先落地在写任何分页代码之前先把“数据从哪来”这件事定下来。分页库本身不负责网络请求它只负责调度。真正发请求的是你的DataSource而请求需要 baseUrl 和鉴权信息。如果每个开发者本地各写一套 Key代码提交后就会互相覆盖线上环境更是灾难。TaoToken 在这里扮演的角色是统一的大模型 API 通道你拿到一个 Key通过固定的 baseUrl 发请求就能调用背后的模型能力。对分页场景来说这意味着一件事——你的DataSource里只需要关心“第几页、每页多少条”鉴权和路由交给统一配置。先做两件事。第一去控制台创建一个 API Key。入口在这里API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建完之后你会得到一串以sk-开头的字符串。注意这串东西不要硬编码进代码也不要提交到 Git。第二确认你要调用的接口地址。TaoToken 的 API 根地址是https://taotoken.net/api这个地址后面会作为 Retrofit 的 baseUrl。注意它不带任何查询参数路径拼接在代码里做。如果你还不确定该用哪个模型、或者想先在网页上试一下请求长什么样可以先用模型对话页面手动发一条消息观察返回结构模型对话体验https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite这一步的意义在于你提前知道了响应体的字段名后面写DataSource解析 JSON 时就不会猜。很多人卡在分页不显示其实是解析字段写错了跟 Paging 一点关系都没有。关于 Key 的存放推荐放在local.properties或者项目的gradle.properties后者不要提交然后通过BuildConfig注入。下面会给具体写法。3. 可复制的工程配置依赖、BuildConfig 与网络层骨架这一节是全文的核心操作区分三块Gradle 依赖、Key 注入、Retrofit 骨架。每一块都给完整代码你直接抄改即可。3.1 build.gradle 依赖片段先确认你的项目用的是 AndroidX。Paging 3 是当前主流版本和协程配合最好。在 app 模块的build.gradle里加dependencies { def paging_version 3.2.1 def lifecycle_version 2.6.2 def retrofit_version 2.9.0 def okhttp_version 4.12.0 // Paging 运行时 implementation androidx.paging:paging-runtime:$paging_version // 仅测试用不依赖 Android 框架 testImplementation androidx.paging:paging-common:$paging_version // 可选RxJava 支持用协程的话可以不引 // implementation androidx.paging:paging-rxjava3:$paging_version // ViewModel LiveData implementation androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version implementation androidx.lifecycle:lifecycle-livedata-ktx:$lifecycle_version // 网络 implementation com.squareup.retrofit2:retrofit:$retrofit_version implementation com.squareup.retrofit2:converter-gson:$retrofit_version implementation com.squareup.okhttp3:okhttp:$okhttp_version implementation com.squareup.okhttp3:logging-interceptor:$okhttp_version }如果你还在用旧版android.arch.paging建议直接升到 AndroidX旧版的LivePagedListBuilder和 Paging 3 的Pager写法差异很大混用会报找不到符号。版本号不要照抄用你项目里已有的 BOM 或统一版本管理避免冲突。3.2 把 Key 注入 BuildConfig在 app 模块的build.gradle顶部android {}块外面或里面加读取逻辑def localProperties new Properties() def localFile rootProject.file(local.properties) if (localFile.exists()) { localProperties.load(new FileInputStream(localFile)) } android { // ... 其他配置 buildTypes { debug { buildConfigField String, TAOTOKEN_API_KEY, \${localProperties[TAOTOKEN_API_KEY] ?: }\ buildConfigField String, TAOTOKEN_BASE_URL, \https://taotoken.net/api/\ } release { buildConfigField String, TAOTOKEN_API_KEY, \${localProperties[TAOTOKEN_API_KEY] ?: }\ buildConfigField String, TAOTOKEN_BASE_URL, \https://taotoken.net/api/\ } } }然后在local.properties里加一行这个文件默认在.gitignore里TAOTOKEN_API_KEYsk-你的真实key注意 baseUrl 末尾的斜杠Retrofit 要求 baseUrl 以/结尾否则拼接路径时会丢掉最后一段。这是新手最常踩的坑之一。3.3 Retrofit 与鉴权拦截器骨架新建一个NetworkModule用 OkHttp 拦截器统一加 Headerobject NetworkModule { private val authInterceptor Interceptor { chain - val request chain.request().newBuilder() .addHeader(Authorization, Bearer ${BuildConfig.TAOTOKEN_API_KEY}) .addHeader(Content-Type, application/json) .build() chain.proceed(request) } private val okHttpClient OkHttpClient.Builder() .addInterceptor(authInterceptor) .addInterceptor(HttpLoggingInterceptor().apply { level HttpLoggingInterceptor.Level.BODY }) .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .build() val apiService: TaoTokenApiService by lazy { Retrofit.Builder() .baseUrl(BuildConfig.TAOTOKEN_BASE_URL) .client(okHttpClient) .addConverterFactory(GsonConverterFactory.create()) .build() .create(TaoTokenApiService::class.java) } }接口定义先写一个最小可用的interface TaoTokenApiService { GET(models) suspend fun listModels(): ModelListResponse }这里的models路径是相对 baseUrl 的最终请求地址是https://taotoken.net/api/models。如果你要调对话接口路径和请求体按文档来鉴权方式不变。4. 分页数据源初始化与验证请求配置搭好之后先别急着写完整的分页 UI。第一步是验证“网络通道 Key”是通的否则后面分页报错你分不清是网络问题还是分页问题。4.1 写一个最小的 PagingSourcePaging 3 的核心是PagingSource。先写一个骨架把加载逻辑留出来class ModelPagingSource( private val api: TaoTokenApiService ) : PagingSourceInt, String() { override suspend fun load(params: LoadParamsInt): LoadResultInt, String { val page params.key ?: 1 return try { val response api.listModels() val items response.data.map { it.id } LoadResult.Page( data items, prevKey if (page 1) null else page - 1, nextKey if (items.isEmpty()) null else page 1 ) } catch (e: Exception) { LoadResult.Error(e) } } override fun getRefreshKey(state: PagingStateInt, String): Int? { return state.anchorPosition?.let { anchor - state.closestPageToPosition(anchor)?.prevKey?.plus(1) ?: state.closestPageToPosition(anchor)?.nextKey?.minus(1) } } }LoadResult.Page的三个参数分别是本页数据、上一页 key、下一页 key。首页时prevKey传 null没有更多数据时nextKey传 nullPaging 就知道到底了。4.2 用 Pager 组装class ModelRepository(private val api: TaoTokenApiService) { fun getModels(): FlowPagingDataString { return Pager( config PagingConfig( pageSize 20, prefetchDistance 40, enablePlaceholders false ), pagingSourceFactory { ModelPagingSource(api) } ).flow } }pageSize是每页条数prefetchDistance是提前多少条开始预加载一般设成 pageSize 的两倍。enablePlaceholders在数据总量不确定时建议关掉否则列表会显示一堆空白占位。4.3 验证动作先跑通一次请求在 ViewModel 里收集这个 Flow并在日志里打印class ModelViewModel : ViewModel() { private val repository ModelRepository(NetworkModule.apiService) val models: FlowPagingDataString repository.getModels() .cachedIn(viewModelScope) }然后在 Activity 里用lifecycleScope收集先不接 RecyclerView只打日志lifecycleScope.launch { viewModel.models.collect { pagingData - Log.d(PagingCheck, 收到一页 PagingData: $pagingData) } }如果你在 Logcat 里看到PagingCheck打出了内容说明 Key 鉴权通过、baseUrl 正确、PagingSource 被正常触发。这一步成功后面的 UI 接入只是时间问题。5. 本篇常见错误排查分页链路第一次跑报错集中在几个地方。我把高频问题和判断方法列出来你对照着查。401 或 403Key 没注入成功。检查BuildConfig.TAOTOKEN_API_KEY是否为空可以在代码里临时打一行Log.d(Key, BuildConfig.TAOTOKEN_API_KEY)。如果为空说明local.properties没读到或者 Gradle 没同步。改完local.properties一定要点 Sync。404baseUrl 拼接错了。确认 baseUrl 是https://taotoken.net/api/末尾有斜杠接口路径不要以/开头否则 Retrofit 会把它当成绝对路径丢掉 baseUrl 的路径部分。找不到 PagingSource 符号依赖没引对。Paging 3 的类在androidx.paging包下如果你引的是android.arch.paging那是旧版类名完全不同。检查build.gradle里的paging-runtime版本。列表一直转圈不加载PagingSource.load抛异常被吞了。把LoadResult.Error(e)里的异常打出来常见的是 JSON 解析失败字段名和响应体对不上。用模型对话页面先看一眼真实响应结构。重复请求同一页getRefreshKey写错导致刷新时 key 计算异常。检查anchorPosition的逻辑确保prevKey和nextKey的加减方向正确。编译报错Unresolved reference: cachedIncachedIn是 Paging 3 的扩展函数需要paging-runtime依赖且要在viewModelScope里调用。确认依赖和导入都正确。排查顺序建议先确认网络通用模型对话页面手动发一次再确认 Key 注入打日志最后才怀疑分页逻辑。大部分问题在前两步就能定位。6. 下一步把分页接到 UI以及长期编码场景的通道选择到这里你的工程已经具备了跑通分页的全部前置条件依赖齐了、Key 注入了、网络通道验证过了、PagingSource 骨架也写好了。下一篇我会把PagingDataAdapter接上 RecyclerView处理加载状态和重试。如果你在接入过程中遇到鉴权或路径问题直接翻接入文档对照参数接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你打算把这个通道用在长期的编码辅助或 Agent 场景里比如让模型帮你生成 DataSource 模板、批量改 Adapter可以考虑 Coding Plan额度和管理方式更适合持续调用Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后提醒一句local.properties里的 Key 千万别提交团队协作时让每个人自己配。分页库本身不难难的是把数据来源这一层管干净。这一层理顺了后面写多少页都是同一套骨架。