dilib — упрощённый инструмент доступа к интерфейсам
Проектные зависимости
- cglib 3.2.0
- gson 2.6.1
- httpclient 4.5.1
- commons-logging 1.2
API-документ
1. Пакет com.loong.dilib
- ApiFactory — класс фабрики сущностей API.
- Методы:
- Object createApi(String className) — создаёт объект сущности API.
- <T> T createApi(Class<T> targetClass) — создаёт объект сущности API.
- ApiProxyFactory — класс фабрики прокси API.
- setCache(ApiCache cache) — добавляет обработчик кэша.
- setShowLog(Boolean showLog) — включает или выключает логирование (по умолчанию выключено).
- createApiProxy() — создаёт прокси класса API.
2. Пакет com.loong.dilib.annotation
- @DIRequest — аннотация запроса интерфейса. Используется для классов и методов интерфейсов API.
- DIRequest.Method — тип метода запроса. По умолчанию GET, можно использовать POST.
- @DIResponse — аннотация ответа интерфейса. Используется для классов и методов интерфейсов API.
- DIResponse.Type — формат ответа.
- STRING — строковый ответ (не используется, метод интерфейса API должен напрямую возвращать строку String).
- JSON — ответ в формате JSON (используется по умолчанию).
- JSONP — ответ в формате JSONP.
-
XML — ответ в формате XML (в настоящее время не поддерживается).
- @DIHeader — аннотация заголовка запроса. Используется в качестве аннотации параметров метода интерфейса API.
- @DICookie — аннотация cookie запроса. Используется в качестве аннотации параметров метода интерфейса API.
- @DIJson — аннотация тела JSON запроса. Используется в качестве аннотации параметров метода интерфейса API.
- @DIPath — аннотация параметров REST. Используется в качестве аннотации параметров метода интерфейса API.
- @DIParam — аннотация параметра запроса. Используется в качестве аннотации параметра метода интерфейса API, в основном используется для указания имени простого параметра доступа.
- @DICache — аннотация конфигурации кэша. Используется для классов и методов интерфейса API. Время кэширования указывается в секундах.
3. Пакет com.loong.dilib.exception
- DIAnnotationException — исключение при ошибке аннотирования интерфейса. Возникает при создании интерфейса API с ошибкой аннотирования.
- DIConnectException — исключение ошибки соединения при доступе к интерфейсу. Возникает, когда доступ к интерфейсу завершается неудачно.
- DIFormatException — исключение неправильного формата ответа при доступе к интерфейсу. Возникает после успешного доступа к интерфейсу, но при неправильном формате ответа.
4. Пакет com.loong.dilib.cache
- ApiCache — интерфейс класса кэша API.
- AbstractApiCache — абстрактный класс кэша API. Реализует метод buildKey().
- MemoryApiCache — простой обработчик памяти кэша.
Использование
Простой пример
Интерфейс API:
public interface TestApi {
@DIRequest("http://xxx/test")
public String test(@DIParam("p") int value);
@DIRequest("http://xxx/test2")
public String test2(Bean bean);
}
Класс Bean:
public class Bean {
private String p1;
private String p2;
// get set
// ......
}
Простое использование:
TestApi api = ApiFactory.createApi(TestApi.class);
String html = api.test(1);
Bean bean = new Bean();
bean.setP1("111");
bean.setp2("222");
String htnl2 = api.test2(bean);
- Вызов
api.test(1) эквивалентен запросу GET http://xxx/test?p=1.
- Вызов
api.test2(bean) эквивалентен запросу GET http://xxx/test2?p1=111&p2=222.
В среде Spring:
<bean id="testApi" class="com.loong.dilib.ApiFactory" factory-method="createApi">
<constructor-arg value="com.test.TestApi" />
</bean>
@Service
public interface Test {
@Resource
private TestApi api;
public String test() {
String html = api.test(1);
}
}
Более сложный пример
@DIRequest("http://xxx")
@DIResponse(Type.JSONP)
public interface TestApi {
@DIRequest(value = "test", method = DIRequest.Method.POST)
@DIResponse
@DICache(3600)
public Result<Test> test(
@DIHeader Map<String, ?> h1,
@DIHeader HBean h2,
@DIHeader("xxx") String h3,
@DICookie Map<String, ?> c1,
@DICookie CBean c2,
@DICookie("xxx") String c3,
@DIJson PBean p
);
@DIRequest(value = "test2", method = DIRequest.Method.POST, charset = "GBK")
@DICache(60)
public Map<String, Linked<Test2>> test2(
@DIHeader Map<String, ?> h1,
@DIHeader HBean h2,
@DIHeader("xxx") String h3,
@DICookie Map<String, ?> c1,
@DICookie CBean c2,
@DICookie("xxx") String c3,
Map<String, ?> p1,
PBean p2,
@DIParam("xxx") String p3
);
@DIRequest(value = "test3/{xxx}/{x2}/{x3}", method = DIRequest.Method.POST)
public Map<String, Linked<Test2>> test3(
@DIHeader HBean h,
@DICookie CBean c,
PBean p,
@DIPath Map<String, ?> path1,
@DIPath PathBean path2,
@DIPath("xxx") String path3,
);
}
Объяснение:
- @DIHeader
- Помечает параметр метода как заголовок запроса.
- В одном методе может быть несколько параметров.
- Используется следующим образом:
example(@DIHeader Map<String, ?> h)example(@DIHeader Bean h)example(@DIHeader("name") String h)
- @DICookie
- Помечает параметр метода как cookie запроса.
- В одном методе может быть несколько параметров.
- Используется следующим образом:
Примечание: в тексте запроса есть код на языке Java, который не был переведён. Пример (@DICookie Map<String, ?> c)
Пример (@DICookie Bean c)
Пример (@DICookie("name") int c)
3. @DIPath
- Обозначает метод как параметр REST.
- В методе может быть несколько параметров.
- Параметр будет обозначен значением {name}, которое заменяет @DIRequest в пути доступа.
- Избыточные поля будут игнорироваться (если не найдено соответствующее {name}).
- Использование:
- Пример (@DIPath Map<String,?> p).
- Пример (@DIPath Bean p).
- Пример (@DIPath("name") String p).
4. Доступ к параметрам запроса
- Параметры, помеченные @Param или не помеченные @DIHeader, @DICookie или @DIPath, считаются параметрами запроса.
- Может быть несколько параметров в одном методе.
- Использование:
- Пример (Map<String,?> p).
- Пример (Bean p).
- Пример (@Param("name") String p).
5. @DIJson
- Обычно используется для передачи сложных параметров запроса.
- Отмеченный параметр преобразуется в формат JSON и добавляется в тело запроса.
- Используется только в методе POST.
- Автоматически добавляет заголовок информации Content-Type = application/json.
- Только один параметр может использоваться в одном методе.
- Использование:
- Пример (@DIJson Map<String,?> p).
- Пример (@DIJson Bean p).
6. @DIRequest
- Пользователь комментирует путь запроса и способ запроса.
- Метод и параметры charset интерфейса @DIRequest недействительны, действительны только методы интерфейса.
- DIRequest.Method.GET является методом запроса по умолчанию.
- Кодировка по умолчанию — UTF-8.
7. @DIResponse
- Если тип возвращаемого значения метода интерфейса — String, содержимое тела ответа будет возвращено напрямую.
- Можно использовать на интерфейсе класса и методе интерфейса, если метод интерфейса не используется, то берётся комментарий интерфейса класса, а если интерфейс класса не используется, берётся значение по умолчанию.
- Тип.JSON — обработка по умолчанию.
- Тип.JSONP — обработка для интерфейса JSONP.
8. @DICache
Конкретные инструкции см. ниже.
Создание API сущности
Метод 1: простой способ
TestApi api = ApiFactory.createApi(TestApi.class);
TestApi2 api2 = ApiFactory.createApi(TestApi2.class);
Способ 2: создание через прокси-фабрику API
// Создание новой фабрики прокси API
ApiProxyFactory proxyFactory = new ApiProxyFactory();
// proxyFactory.setShowLog(true);
// Создать прокси-класс API
ApiProxy proxy = proxyFactory.createApiProxy();
TestApi api = proxy.createApi(TestApi.class);
TestApi2 api2 = proxy.createApi(TestApi2.class);
Конфигурация кэша
Простой способ использования
- Добавьте аннотацию @DICache к методу API (или классу интерфейса API) (время в секундах).
- Создайте класс обработки API через фабрику прокси API.
- Внедрите обработчик кэша в фабрику прокси API.
// Обработчик кэша
ApiCache apiCache = new MemoryApiCache();
// Фабрика прокси API
ApiProxyFactory proxyFactory = new ApiProxyFactory();
proxyFactory.setCache(apiCache);
Пользовательский обработчик кэша
- Необходимо реализовать интерфейс ApiCache или унаследовать абстрактный класс AbstractApiCache.
- Интерфейс ApiCache содержит три метода:
- buildKey(Object api, Method method, Object[] params) — создать ключ хранения.
- put(Object api, Mehtod method, String key, String html, int expire) — добавить кэш.
- get(Object api, Mehtod method, String key) — получить кэш.
- Параметры:
- Object api — класс сущности API.
- Mehtod method — метод API.
- Object[] params — набор параметров доступа к методу.
- String key — ключ кэша, созданный с помощью buildKey().
- String html — информация о ответе интерфейса.
- int expire — срок действия (в секундах).
- Абстрактный интерфейс AbstractApiCache уже реализовал метод buildKey().
- MemoryApiCache — это уже написанный простой обработчик кеша, который можно использовать непосредственно для небольшого объёма данных.
Примечание:
- Лучше всего использовать базу данных типа «ключ-значение», такую как Redis, для сохранения кэша.
- Метод buildKey() в AbstractApiCache всё ещё нуждается в оптимизации, особенно для параметров типа Bean, которые содержат Map или Set.
- Ключ кэша, построенный в AbstractApiCache, уже может различать класс интерфейса и метод интерфейса, поэтому при использовании наследования абстрактного класса в методах put() и get() можно напрямую игнорировать параметры Object api и Mehtod method (конечно, их также можно использовать для классификации и хранения).
- На самом деле параметр Object api не имеет особого смысла... из Mehtod method можно получить тип интерфейса, временно сохранить его для удобства прямого использования.
Комментарии ( 0 )