Универсальный фреймворк на основе Voovan для RESTful сервисов. Цель — предоставить широкому кругу разработчиков быстрый, надёжный, функционально богатый и самодокументируемый фреймворк для RESTful сервисов. Это модуль проекта Voovan, который следует добавить в проект Voovan WebServer.#### Основные характеристики:

• Два аннотирования позволяют автоматически вывести метод как RESTful интерфейс и сгенерировать полное описание RESTful API.
• Автоматическое распознавание переменных пути, обычных запросных переменных, URL-encoded и multipart отправляемых переменных. Приоритет источника переменной: путь > URL-encoded и multipart > обычные запросные переменные.
• Поддержка методов HTTP протокола и произвольных пользовательских методов HTTP.
• Поскольку HTTP запросы передаются в виде строки, типы параметров метода поддерживаются простыми Java базовыми типами, коллекциями, Map и пользовательскими типами.
• Количество параметров метода, типы возвращаемого значения и прочее не ограничены, могут быть любыми. Если метод возвращает объект, он будет автоматически преобразован в JSON строку.
• Для доступа к документации следует добавить ! после соответствующего URL интерфейса. Например, если маршрут интерфейса /test, то документация доступна через /test!.
• В конфигурационных параметрах можно внедрять свойства в классах, используя соответствующие методы установки.
• Возможность прямого взаимодействия с Java классами сервера через JavaScript на странице, обеспечивая беспрепятственный обмен данными между клиентом и сервером. Поддержка безопасности:
  • 1. Управление доступом к классам, чтобы контролировать, какие классы могут быть использованы из клиента.
  • 2.Управление псевдонимами классов или пакетов, скрывая пути к классам или полные названия классов от пользователя.
  • 3. Управление временем жизни экземпляров классов на стороне клиента, предотвращая OutOfMemoryError. Объекты будут автоматически обновлены при каждом обращении к методам.

Пример использования служебных методов: http://vestful.voovan.org/vestful/test!

Пример вызова метода с возвратом объекта: http://vestful.voovan.org/vestful/test/testWithReturnObject!

Пример вызова Java класса: http://vestful.voovan.org

Первый шаг: подготовка окружения для работы Vestful

• Установка VoovanServer:

Скачать## Обновление до последней версии VoovanServer и изменение конфигурационного файла web.json

// Конфигурационный файл: conf/web.json
"Modules": [
    {
        "Name": "Модуль Vestful",                                      // Название модуля
        "Path": "/vestful",                                            // Путь модуля
        "ClassName": "org.voovan.vestful.RestfulModule"                // Класс обработчика модуля
    }
]
```### Два. Создание бизнес-классов
#### Описание аннотаций:
- Аннотация Restful
    - Способ использования: применяется к методам.
    - Параметры:
        - method / тип HTTP запроса. Например: GET, POST, PUT и т.д.
        - desc / описание метода.
- Аннотация Param
    - Способ использования: применяется к параметрам методов.
    - Параметры:
        - name: имя параметра.
        - desc: описание параметра.
- Пример использования аннотаций:
```java
// Класс: org.voovan.test.restful.TestClass.java
// Метод с аннотацией
@Restful(method = "LOCK", desc = "Это описание метода. тестовый параметр типа float")
public static TestResult testWithReturnObject(
        @Param(name = "test1", desc = "Имя параметра test1, тип String") // Аннотация параметра
                String test1,
        @Param(name = "test2", desc = "Имя параметра test2, тип int") // Аннотация параметра
                int test2){
    return new TestResult(test1, test2);
}

------------------------------------------### Три. Изменение конфигурационного файла

Измените конфигурационный файл conf/vestful.json.

Добавьте следующий контент в конфигурационный файл:

// Конфигурационный файл: conf/vestful.json
[
    {
        "name": "тест",
        "route": "/тест",
        "classPath": "org.voovan.test.restful.TestClass", // Бизнес-класс, созданный в предыдущем шаге
        "desc": "это тестовый интерфейс."
    }
]

• name: название интерфейса
• route: маршрут для поиска сервиса; если этот узел отсутствует, то значение по умолчанию будет равно имени класса, указанному в classPath, например: org.voovan.restful.TestClass, тогда маршрут по умолчанию будет равен /TestClass
• classPath: путь к классу, предоставляющему интерфейс
• desc: описание интерфейса------------------------------------------

Пример использования:

Пример тестового кода можно найти здесь: org.voovan.test.vestful.TestClass.java

Описание документа:

Класс и тестовая страница: http://x.x.x.x/vestful/test!

• Vestful — это путь доступа к модулю, конфигурированный в web.json.
• test — это маршрут текущего класса, конфигурированный в vestful.json.

Описание метода класса и тестовая страница: http://x.x.x.x/vestful/test/testWithObject!

• Vestful — это путь доступа к модулю, конфигурированный в web.json.
• test — это маршрут текущего класса, конфигурированный в vestful.json.
• testWithObject — имя метода внутри класса.

Выше приведено базовое предоставление RESTful сервиса. Ниже будет рассмотрено, как выполнять операции с объектами Java на сервере через JavaScript на клиентской стороне.

Четвертое: выполнение операций с объектами Java на сервере через JavaScript на клиентской стороне

Измените conf/vestful.json

Добавьте следующее содержание в конфигурационный файл:```json

// Конфигурационный файл: conf/vestful.json [ { "name": "DirectObject", "route": "DirectObject", "classPath": "org.voovan.vestful.entity.DirectObject", "desc": "RESTful API для DirectObject", "params": { // Это полный путь к этому сервису (путь модуля Vestful в web.json + путь маршрута текущего класса) // В данном случае в web.json указан путь "/", а для текущего класса — "DirectObject". Поэтому доступ осуществляется по пути /DirectObject. "route": "DirectObject", // Этот параметр контролирует возможность вызова класса из JavaScript на клиентской стороне // Только те классы, которые указаны в этом списке, могут быть вызваны из JavaScript. "classControl": [ "java.util.ArrayList", "org.voovan.test.vestful.*" ], // Определение псевдонимов для классов "alias": { "OVTV": "org.voovan.test.vestful.TestClass" }, // Управление временем жизни объекта, единицы измерения: секунды "objectAliveTime": 60 } } ]

Импорт Java-класса в JavaScript на странице:

```html
<script lang="javascript" src="/DirectObject/genScript/java.util.ArrayList"></script>

Путь к импортированию JavaScript указан в параметре route конфигурационного файла conf/vestful.json для класса org.voovan.vestful.entity.DirectObject. Добавление genScript в конце пути для представления динамически сгенерированного скрипта серверной части. Например: Конфигурация примера: "route": "DirectObject" Тогда путь к JavaScript будет выглядеть так: /DirectObject/genScript/полное_имя_класса_или_его_синоним_может_быть_использован_для_внесения_объекта_на_страницу.

Использование Java-классов на странице:

// Для более подробной информации обратитесь к WEBAPP/test.html
<script lang="javascript">
    var arrayList1 = new java.util.ArrayList();
    arrayList1.add("aaaa");
    var arrayList2 = new java.util.ArrayList();
    arrayList2.add("bbbb");
    // Поддержка взаимной ссылки объектов Java, созданных на клиентской стороне
    arrayList1.addAll(arrayList2);
    // Вручную освобождает объекты; если это не сделано, они будут освобождены согласно времени жизни, указанному в конфигурационном файле
    arrayList1.release();
    arrayList2.release();
</script>