97 lines
2.6 KiB
Markdown
97 lines
2.6 KiB
Markdown
# client_proxy_framework
|
||
|
||
通用代理 API 框架。**接口请求已按原始字段名写好**，不同应用只需**修改映射表**即可接入不同后端。
|
||
|
||
**新建换皮应用**：请阅读 [docs/create_new_skin_app.md](docs/create_new_skin_app.md)（`skin_config.json` + `ClientBootstrap` 全流程）。
|
||
|
||
## 设计思路
|
||
|
||
- **业务层**：统一使用**原始字段名**（canonical），如 `deviceId`、`userId`、`credits`、`userToken`
|
||
- **映射层**：`FieldMapping` 负责 原始 ↔ V2 互转
|
||
- **换皮应用**：只需提供自己的 `fieldMapping`，无需改业务代码
|
||
|
||
## 使用方式
|
||
|
||
### 1. 添加依赖
|
||
|
||
```yaml
|
||
dependencies:
|
||
client_proxy_framework:
|
||
path: ../client_proxy_framework # 与 app_client_1 同级
|
||
```
|
||
|
||
### 2. 实现配置
|
||
|
||
```dart
|
||
class MyAppConfig extends AppConfig {
|
||
@override
|
||
String get appId => 'YourAppId';
|
||
@override
|
||
String get packageName => 'com.yourapp.package';
|
||
@override
|
||
String get aesKey => 'your-16-char-key';
|
||
@override
|
||
String get preBaseUrl => 'https://pre-api.example.com';
|
||
@override
|
||
String get prodBaseUrl => 'https://api.example.com';
|
||
@override
|
||
String get proxyPath => '/quester/defender/summoner';
|
||
|
||
// 若后端 V2 字段名不同，覆盖此方法
|
||
@override
|
||
FieldMapping get fieldMapping => myCustomFieldMapping;
|
||
}
|
||
```
|
||
|
||
### 3. 初始化并调用
|
||
|
||
```dart
|
||
void main() {
|
||
ApiClient.init(MyAppConfig());
|
||
runApp(MyApp());
|
||
}
|
||
|
||
// 使用原始字段名调用
|
||
final res = await UserApi.fastLogin(
|
||
deviceId: deviceId,
|
||
sign: sign,
|
||
referer: referer,
|
||
);
|
||
if (res.isSuccess) {
|
||
final data = res.data as Map<String, dynamic>;
|
||
ApiClient.instance.setUserToken(data['userToken']); // 原始字段名
|
||
UserState.setCredits(data['credits']);
|
||
}
|
||
```
|
||
|
||
## 内置 API 服务（均使用原始字段名）
|
||
|
||
| 服务 | 方法示例 |
|
||
|------|----------|
|
||
| UserApi | fastLogin, referrer, getCommonInfo, getAccount |
|
||
| PaymentApi | getGooglePayActivities, getPaymentMethods, createPayment, googlepay |
|
||
| ImageApi | getCategoryList, getImg2VideoTasks, getProgress, getUploadPresignedUrl, createTask, getMyTasks |
|
||
|
||
## 映射表
|
||
|
||
单一映射表：**原始字段 → 后端字段**。请求时按此转换，响应时自动取反。
|
||
|
||
```dart
|
||
const myMapping = FieldMapping({
|
||
'deviceId': 'origin',
|
||
'userId': 'asset',
|
||
'userToken': 'reevaluate',
|
||
'credits': 'reveal',
|
||
// ... 后端文档给的映射表直接填入即可
|
||
});
|
||
```
|
||
|
||
## 可配置项
|
||
|
||
| 配置项 | 说明 |
|
||
|--------|------|
|
||
| fieldMapping | 字段映射表，换皮应用主要修改此项 |
|
||
| proxyKeys | 代理请求体字段名 |
|
||
| v2SanctumPath | V2 嵌套路径 |
|
||
| responseCodeField / responseMsgField / responseDataField | 响应结构字段名 |
|