предисловие
В прошлом завершение веб-сайта всегда было «все в одном», а страница, данные и рендеринг выполнялись на стороне сервера.Самым большим недостатком этого было постобслуживание, и расширение было чрезвычайно болезненным. должен иметь как фронтенд, так и бэкэнд знания. Так медленно это появилось前后端分离подумал о:
Бэкенд отвечает数据编造, а интерфейс отвечает за数据渲染, внешняя статическая страница вызывает указанный API для получения данных в фиксированном формате, а затем отображает данные, которые представляются пользователю — это «динамический» процесс, и дизайн этой части API стал проблема. Как разработать простой для понимания и простой в использовании API становится проблемой.
И так называемыйrestfulЭто ограничение используется для стандартизации нашего API.
вводить
restдаREpresentational State TransferАббревиатура из трех слов, введенная Роем Филдингом в статье 2000 года, означает архитектурный стиль распределенных сервисов. И если вы хотите, чтобы ваш API назывался Restful API, просто следуйте ограничениям, которые он предусматривает.
остальные принципы проектирования
- Клиент-сервер: отделив пользовательский интерфейс от хранилища данных, мы можем упростить серверный компонент, чтобы улучшить переносимость и масштабируемость пользовательского интерфейса на нескольких платформах. Это можно сравнить с идеей разделения переднего и заднего концов.
- Без сохранения состояния: каждый запрос от клиента к серверу должен содержать всю информацию, необходимую для понимания запроса, и не может использовать какой-либо сохраненный контекст на сервере. Это означает, что вы должны максимально избегать использования сеансов и позволять клиенту самому определять состояние сеанса. (жетон)
- Спецификация интерфейса: определение ограничения интерфейса REST: идентификация ресурса, действие запроса, информация об ответе, указывает, что вы хотите работать через uri.
资源, идентифицируйте операцию, которая должна быть выполнена через действие запроса (метод http), и укажите результат выполнения этого запроса через возвращаемый код состояния. - Кэшируемость: ограничение кэширования требует, чтобы данные в ответе на запрос были неявно или явно помечены как кэшируемые или некэшируемые. Если ответ можно кэшировать, кэш клиента имеет право повторно использовать данные ответа для будущих эквивалентных запросов. Указывает, что заголовок ответа на запрос на получение должен указывать, имеется ли кешируемый заголовок (Cache-Control). Среди них 1, 2, 3 ограничения являются наиболее важными, а 1 легко понять. Далее мы поговорим о принципах безгражданства и канонических интерфейсах.
спецификация URI
Описание ресурса составляет URI, который обычно имеет следующие ограничения:
- Используйте существительные. например пользователь, студент, класс
API.example.com/class - ругать за это...
- Используйте метод http для соответствия различным действиям запроса (база данных или бизнес-логика)
GET: операция запроса:
HTTP GET /devices?startIndex=0&size=20 означает получение списка устройств в соответствии с условиями запроса
HTTP GET /configurations?startIndex=0&size=20
HTTP GET /devices/{id}/configurations
HTTP GET /devices/{id}
POST: Добавить операцию:
HTTP POST /device означает добавление нового устройстваPUTОперация обновления (представляет собой обновление всех свойств объекта)
HTTP PUT /devices/{id} означает обновление устройства (различие уникального идентификатора устройства)PATCHЧастичное обновление (представляет собой обновление некоторых атрибутов сущности) из-за проблем с совместимостью браузера, обычно рекомендуется использовать put
HTTP PATCH /devices/{id} означает обновление некоторых свойств устройства.
DELETEудалить операцию
HTTP DELETE /devices/{id} означает удаление устройства, отличающегося идентификатором
- Используйте дефисы (-) вместо (_), чтобы улучшить читаемость URI.
API.example.com/inventory - нет...// более читабельно
API.example.com/inventory_no…// более подвержен ошибкам
-
Используйте строчные буквы в URI (кроме особых случаев, таких как имена собственные)API.example.org/no-folder/no…
-
Не используйте расширения файлов. Расширения файлов выглядят плохо и не добавляйте никаких преимуществ. Удаление их также уменьшает длину URI. нет причин держать их
API.example.com/device-mana… / не используй это /
API.example.com/device-mana…/* Это правильный URI */
-
Используйте компонент запроса для фильтрации коллекции URI.
Много раз мы сталкиваемся с требованием для набора ресурсов, которые необходимо сортировать, фильтровать или ограничивать на основе некоторых конкретных свойств ресурсов. Для этого не создавайте новый API — вместо этого включите сортировку, фильтрацию и разбиение на страницы в API коллекции ресурсов и передавайте входные параметры в качестве параметров запроса. Например
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
- не использовать в конце
/
Как последний символ в пути URI, косая черта (/) не добавляет семантического значения и может привести к путанице. От них лучше отказаться совсем.
- Используйте код состояния http для определения результата выполнения API
1хх: ИнформацияКоммуникация передает информацию на уровне протокола.
2xx: успехУказывает, что запрос клиента был успешно принят.
3xx: перенаправлениеУказывает, что клиент должен выполнить некоторые дополнительные действия для выполнения своего запроса.
4xx: ошибка клиентаТакие коды состояния ошибки указывают на клиента.
5xx: ошибка сервераСервер несет ответственность за эти коды состояния ошибки. Кроме того, полные и более подробные коды состояния здесь не повторяются. Как правило, упрощенная версия API будет использовать 200, 400 и 500, из которых 400 представляет ошибку в вызове клиента, а конкретная информация об ошибке бизнес-логики помещается в тело ответа:
{
"error": "username.or.password.error"
}
-
определение версии API
Когда нам нужно обновить существующий интерфейс API, потому что интерфейс API был введен в действие, новый добавленный бизнес не может быть гарантированно совместим с исходной логикой.В настоящее время требуется новый интерфейс, и этот интерфейс обычно указывает, что оригинальный интерфейс обновляется (разные версии), как определить версию?
- Версии URI (рекомендуется)api.example.com/v1 apiv1.example.com
- Управление версиями с пользовательскими заголовками запросов Accept-версия: v1 Accept-версия: v2
- Управление версиями с заголовком Accept Принять:application/vnd.example.v1+json Принять: приложение/vnd.example+json;версия=1.0
нет статуса
Есть несколько очень существенных преимуществ в том, чтобы сделать REST API без сохранения состояния:
-
Stateless помогает масштабировать API для миллионов одновременных пользователей, развертывая API на нескольких серверах. Любой сервер может обработать любой запрос, так как нет зависимостей, связанных с сеансом. (кластер)
-
Отсутствие состояния делает REST API менее сложным — вся логика синхронизации состояния на стороне сервера может быть удалена. (удалить сессию, очистить лишнее место)
-
API без сохранения состояния также легко кэшируются. Определенное программное обеспечение может решить, следует ли кэшировать результат HTTP-запроса, просматривая этот единственный запрос. Нет никакой двусмысленности в том, что состояние, полученное из предыдущих запросов, может повлиять на кешируемость этого запроса. Это повышает производительность приложения.
-
Сервер никогда не забывает личность каждого клиента», потому что клиент отправляет всю необходимую информацию в каждом запросе (переносит токен).
Итак, как можно добиться безгражданства? Как мы уже говорили ранее, сервер больше не должен сохранять сеанс сеанса, вся эта работа идентифицируется по http-запросу, и наиболее распространенным способом является использование токена. Для создания токенов рассмотрите возможность использования jwt и oauth. Среди них jwt может сослаться на другую мою статью:wooooooo.brief.com/afraid/6method0oh30very…
Суммировать
Сначала мы представляем предысторию сервиса rest, знакомим с архитектурой rest и, наконец, фокусируемся на дизайне ограничений API-интерфейса rest.
关注我，这里只有干货！