重构运行时 API 命名与服务资源模型

[nicefan]

背景

当前运行时 API 中 Http、Resource、serviceInit、factory 等概念存在一定职责重叠，尤其在以下场景下心智模型不够清晰：

• Http 负责统一请求抽象，但真正的请求实现由 adapter 提供。
• Resource 既承担服务能力扩展，又被用于创建业务 API。
• factory() / serviceInit() 会把“配置绑定”“服务派生”“业务 API 创建”混在一起。
• 微服务场景下，希望基于同一套服务配置仅修改 base path 即可派生出新的服务资源。
• 第三方服务（例如地图 API）应允许直接基于底层 Http 扩展出一套独立服务能力，而不依赖默认业务 Resource。

本任务只讨论和重构运行时 API，不涉及 codegen。

目标

重新梳理运行时 API 的命名和层级，使下列概念清晰且职责单一：

1. 底层统一请求抽象。
2. adapter 作为实际请求实现的适配层。
3. 一套“请求能力 + 服务配置”的服务资源定义。
4. 基于相同配置派生微服务，仅调整 base path。
5. 从服务资源创建最终业务 API。
6. 明确每个阶段返回值和推荐变量命名。

当前讨论方向

底层请求层

暂定继续保留 Http 作为底层统一请求抽象，因为它本身并不是具体 client，真正的请求实现由 adapter 提供。

需要继续评估：

• Http 是否保留现名，还是使用更准确的替代命名。
• Adapter 是否调整为 HttpAdapter。
• adapter 标准返回值是否定义为 HttpResponse<T>。
• 请求级配置是否统一为 RequestOptions。
• Resource 构造配置是否统一为 ResourceOptions 或新的服务配置类型。

服务资源层

当前 Resource extends Http，默认增加 upload()、downloadFile() 等公共服务能力，并允许业务继续继承扩展。

需要重新评估 Resource 这个名字是否准确。候选方向包括：

• Resource
• Service
• 其他更能表达“基于 Http 的服务能力定义”的命名

要求：

• 业务项目可以继承默认服务能力，例如 AppService extends Service。
• 第三方服务可以直接基于底层请求层扩展，例如地图服务直接继承 Http。

配置与服务绑定

核心目标是让 config 与某套服务能力绑定，而不是依赖全局配置或一次性 factory 闭包。

需要设计一种自然的 API，使：

• 一套服务配置可以被保留和复用。
• 可以派生新的微服务，只修改 base path 或少量 override。
• 不应让普通 Resource 实例同时承担 get/post 与 clone/createApi 等构造职责，避免实例职责混杂。

可评估的方向包括：

const backend = Service.configure(options)
const system = backend.clone('system')
const userApi = system.createApi('user', ...)

其中 configure() 返回的应是“已绑定服务类型和配置的服务定义”，而不是直接发请求的 Resource 实例。

微服务派生

目标用法：

const backend = ...
const systemService = backend.clone('system')
const workflowService = backend.clone('workflow')

要求：

• 继承原服务配置和服务能力类型。
• 只修改 base path 时应足够简洁。
• 支持完整配置 override 的高级场景。
• 派生后的服务仍保持原扩展类型能力。

业务 API 创建

目标用法方向：

const userApi = systemService.createApi('user', resource => ({
  list(query) {
    return resource.get('list', query)
  },
}))

需要明确：

• createApi() callback 中对象的正式称呼和类型。
• createApi() 最终返回值统一称为“业务 API”，变量建议为 userApi、orderApi 等。
• 是否继续暴露底层 resource，以及如何避免 $http、mixin 和方法重名问题。

单次请求返回值

当前 request/get/post/... 返回 Promise<T>，后续需要结合 setMessage() 的请求级上下文重新评估。

候选：

• ApiRequest<T>
• 保持普通 Promise<T>，通过其他方式暴露请求上下文

setMessage() 需要保持“请求完成后、最终消息输出前可修改当前接口消息”的能力，同时避免并发请求间互相覆盖。

命名需要最终确认的清单

• Http
• Resource
• Adapter
• DefOptions
• RequestConfig
• adapter 返回值类型
• 服务配置绑定后的返回值类型
• clone() 返回值称呼
• createApi() callback 参数称呼
• createApi() 返回值称呼
• 单次请求返回值类型

验收标准

• 不依赖全局配置即可定义多套独立服务。
• 微服务派生只需少量配置即可完成。
• 第三方 API 可以直接从底层请求抽象扩展独立服务能力。
• 各层命名能从代码本身看出职责，不需要依赖大量文档解释。
• 运行时 API 不引入仅为包装而存在的额外层级。
• 保留现有 Loading / Message 统一协调设计，并修正请求级 setMessage 并发归属问题。
• 最终给出旧 API → 新 API 的迁移方案和兼容策略。