# restlib

**Repository Path**: lihui157/restlib

## Basic Information

- **Project Name**: restlib
- **Description**: android客户端使用的rest接口解析库，支持服务端json数据自动转换本地模型。使用注解定制request
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2017-12-13
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
AIGC:
    ContentProducer: Minimax Agent AI
    ContentPropagator: Minimax Agent AI
    Label: AIGC
    ProduceID: f9b3639620d83e3e74b1c3d921522b8e
    PropagateID: f9b3639620d83e3e74b1c3d921522b8e
    ReservedCode1: 3044022072fcd24255469e5e6932c09a7a17c672deedfae727704c49e77506592fbf44c00220576d77ae6767b784830a0b30a654f3ac56df05c82fb0182b955b1c7a0afca699
    ReservedCode2: 30440220380a0beb8e9be597450df337de00dde7a566d816d10cff97590fc03ee0503f0f0220692d4f61f00d1307fd5f25697bf926cad9728af90e05675968061281dbb9ec4c
---

# restlib

Android客户端使用的REST接口解析库，支持服务端JSON数据自动转换本地模型。使用注解定制请求。

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://gitee.com/lihui157/restlib)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](http://www.apache.org/licenses/LICENSE-2.0)

## 版本更新 (v2.0.0)

### 新增功能

- **OkHttpClient单例模式**：使用全局共享的OkHttpClient实例，避免每次请求都创建新实例，提升性能
- **服务缓存**：使用ConcurrentHashMap缓存已创建的代理实例，重复调用时直接返回缓存
- **CacheManager单例模式**：缓存管理器改为单例，避免重复创建
- **完善的日志记录**：所有异常使用Log替代printStackTrace，便于问题排查
- **更完善的空指针检查**：添加了全面的空指针检查，提升稳定性

### 依赖升级

- OkHttp: 3.4.0 → 4.12.0（修复多个安全漏洞）
- Android SDK: 26 → 34
- Kotlin: 1.9.22
- AppCompat: AndroidX 1.6.1

## 使用方法

### 1. 创建AbsCall子类

AbsCall是接口请求的核心处理类，通过对请求接口注解解析，内部创建完整的HTTP请求格式，并为其子类提供公共参数定制接口，以适应项目中对head、URL中公共参数的定制化。同时提供respFilter方法重写，实现对response数据的预处理。

```java
public class MyCall extends AbsCall {

    protected void addCommonQuery() {
        setQueryNameAndValue("deviceid", deviceId);
        setQueryNameAndValue("appid", APP_ID);
    }

    protected void addCommonHead() {
        setHeadNameAndValue("User-Agent", "Android App");
        setHeadNameAndValue("AUTH", "");
    }

    @Override
    protected String getBaseUrl() {
        return "http://api.xxx.com/v1.0/";
    }

    @Override
    protected void respFilter(String result) {
        try {
            JSONObject jsonObject = new JSONObject(result);
            int status = jsonObject.optInt("Status");
            if (status == 200) {
                super.respFilter(jsonObject.opt("Result").toString());
            } else {
                doError(status + "", jsonObject.optJSONObject("Result").optString("ErrorMsg"));
            }
        } catch (JSONException e) {
            Log.e("MyCall", "JSON parse error", e);
            doError(RestStatus.HTTP_UNDEFINE.value() + "", e.getMessage());
        }
    }
}
```

### 2. 创建Rest接口定义

```java
public interface RestApi {

    @GET("Story/StoryVersion/getRecommendList")
    @Cache(policy = "OutlineFirst", time = 1)
    MyCall getRecommendList(
            @Query("offset") String offset,
            @Query("limit") String limit,
            @Query("test") String test,
            @Head("auth") String auth,
            RestCallback<ResponseData<GetRecommendListReturn>> restCallback);

    @POST("Center/Story/uploadMp3")
    @Multipart
    MyCall upload(
            @Field("sid") String sid,
            @Field("title") String title,
            @FileField("mp3") String mp3Path,
            RestCallback<String> restCallback);

    @POST("Passport/{User}/loginByCode")
    MyCall login(@Field("mobile") String username,
                 @Field("code") String pass,
                 @Path("{User}") String User,
                 RestCallback<LoginReturn> restCallback);
}
```

### 3. 接口调用

```java
final RestApi api = (RestApi) new Rest().create(this, MyCall.class, RestApi.class);

api.login("18684692111",
        "888888",
        "User",
        new RestCallback<LoginReturn>() {
            @Override
            public void error(String code, String errorMsg) {
                Log.e("Login", "Error: " + errorMsg);
            }

            @Override
            public void success(LoginReturn data) {
                Log.d("Login", "Success: " + data.getUserNick());
            }
        });
```

### 4. 高级配置

#### 配置OkHttpClient

```java
// 设置超时时间
OkHttpClientManager.setTimeout(60); // 60秒

// 设置调试模式（打印网络请求日志）
OkHttpClientManager.setDebugMode(true);

// 使用自定义OkHttpClient
OkHttpClient customClient = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .build();
OkHttpClientManager.setClient(customClient);
```

#### 清除服务缓存

```java
// 清除所有服务缓存
Rest.clearServiceCache();

// 清除指定服务缓存
Rest.removeServiceFromCache(RestApi.class);

// 获取缓存的服务数量
int count = Rest.getCachedServiceCount();
```

## 注解说明

| 注解 | 类型 | 说明 |
|------|------|------|
| @POST | 方法注解 | 定义HTTP请求为POST请求 |
| @GET | 方法注解 | 定义HTTP请求为GET请求 |
| @Multipart | 方法注解 | 定义HTTP请求为上传，配合POST使用 |
| @Cache | 方法注解 | 定义当前请求的缓存策略 |
| @Head | 参数注解 | 设置Head参数 |
| @Path | 参数注解 | 设置替换URL中占位符参数 |
| @Field | 参数注解 | 设置POST请求中的表单参数 |
| @FileField | 参数注解 | 设置文件上传请求中的文件本地地址参数 |
| @Query | 参数注解 | 设置URL查询参数 |
| @JsonEntity | 参数注解 | 设置JSON请求体 |

## 缓存说明

本框架提供三种缓存策略：

1. **OutlineFirst**：离线数据优先，如果未过期，直接使用离线数据，不请求线上数据
2. **OnlineFirst**：线上数据优先，保持使用线上数据，同时更新缓存备用。如果网络失败，使用离线数据
3. **Both**：同时使用，先预览离线数据，再更新线上数据，同时更新缓存

示例：`@Cache(policy = "OutlineFirst", time = 1)`

- policy：缓存策略
- time：过期时间，单位为分钟

## 注意事项

1. AbsCall子类必须有一个无参构造函数
2. 回调方法运行在主线程
3. 请求完成后可以调用AbsCall的cancle()方法取消请求
4. 使用@Path注解时，URL中的占位符需要与参数注解的value一致
5. v2.0.0版本已修复多个已知问题，建议升级

## 依赖

```gradle
dependencies {
    implementation 'cn.leestudio:restlib:2.0.0'
}
```

## License

Apache License 2.0

版权所有 (c) 2017-2024 lihui157