предисловие
Написал статью в прошлом году"Спецификация возврата информации об ошибке внутреннего API-интерфейса", которое представляет собой сообщение об ошибке, соответствующее спецификации RESTful (строго говоря, похожее на RESTful). Однако у землекопов разные взгляды на эту норму, и все они склонныПока серверная часть может правильно принять запрос, это 200. Исключения передаются в бизнес-обработку.
И не только спецификация возврата сообщения об ошибке, дизайн API редко соответствует стилю RESTful, большинство из которых представляет собой JSON-подобный RPC. Почему это?
RESTful API
Чтобы ответить на этот вопрос, вы должны сначала узнать, как выглядит RESTful API.
Собственно, про основные понятия RESTful я писал в прошлой статье«Методология: как изучить HTTP»Он также был представлен и не будет повторяться здесь.
Давайте посмотрим, как формируется полноценный RESTful API.
Richardson Maturity Model
Леонард Ричардсон предлагает модель, названную в его честь.Richardson Maturity Model, пошаговое введение в различные уровни перехода на RESTful.
Но важно подчеркнуть, что, хотя RMM — это хороший способ думать о RSET, это не определение REST. RMM полезен только тем, что обеспечивает хороший пошаговый подход к пониманию основной идеи, лежащей в основе идеи REST.
Level 0
Это самый базовый уровень, на котором HTTP просто используется как транспортный туннель для удаленного взаимодействия, а не как транспортный протокол, и не задействует какой-либо веб-механизм. Например:
Я назначил встречу с другом, чтобы поиграть в бадминтон сегодня, поэтому я сделал запрос в спортзал, чтобы узнать, когда можно забронировать площадку для бадминтона.
POST /stadiumReception HTTP/1.1
[various other headers]
{
"date": "2022-01-05",
"sport": "badminton"
}
Стойка регистрации вернется к тому временному интервалу, когда площадка для бадминтона может быть забронирована сегодня.
HTTP/1.1 200 OK
[various headers]
{
"times": [
{
"start": "1400",
"end": "1600"
},
{
"start": "1700",
"end": "1830"
}
]
}
Получите информацию о периоде времени, снова назначьте встречу и решите сделать заказ с 17:00 до 18:30 и закончить трапезу.
POST /stadiumReception HTTP/1.1
[various other headers]
{
"date": "2022-01-05",
"sport": "badminton",
"start": "1700",
"end": "1830"
}
Бронирование успешно!
HTTP/1.1 200 OK
[various headers]
{
"orderId": "123456789"
}
Видно, что это очень типичный формат JSON RPC.Конечно, дизайн API намного лучше, чем в реальной разработке.
Уровень 1: Ресурсно-ориентированный
Первый шаг к вершине REST в модели RMM (модель зрелости Ричардсона) ориентирован на ресурсы, поэтому независимые ресурсы заменяются единым интерфейсным узлом.
Следовательно, различные виды спорта, такие как бадминтон, могут быть абстрагированы в независимые ресурсы. Таким образом, запрос изменяется следующим образом:
POST /sports/badminton HTTP/1.1
[various other headers]
{
"date": "2022-01-05"
}
Спросите о дате, наличии площадок для бадминтона.
HTTP/1.1 200 OK
[various headers]
{
"times": [
{
"start": "1400",
"end": "1600",
"id": "123456789"
},
{
"start": "1700",
"end": "1830",
"id": "987654321"
}
]
}
Возврат имеет отдельный идентификатор, добавленный к исходной основе, который может представлять определенный период простоя площадки для бадминтона.
В это время вы можете выбрать определенный период времени и забронировать его идентификатор в интерфейсе бронирования.
POST /reservations/987654321 HTTP/1.1
[various other headers]
Бронирование успешно!
HTTP/1.1 200 OK
[various headers]
{
"orderId": "abcd987654321"
}
Видно, что самое большое отличие от уровня 0 заключается в том, что работа на одном узле становится работой на разных ресурсах.
Уровень 2: HTTP-глаголы
Level2, который действительно использует HTTP в качестве транспортного протокола, наиболее интуитивно понятно, что Level2 используетHTTP-глаголы, GET/PUT/POST/DELETE/PATCH и т. д. Это все спецификации HTTP. Роль спецификации, естественно, важна. Когда пользователь видит запрос POST, он знает, что это неидемпотентДа, будьте осторожны при использовании. Когда вы видите GET, вы знаете, что он идемпотентный, и вызов его несколько раз не вызовет проблем.Конечно, предполагается, что проектировщики и разработчики API также следуют этому набору спецификаций.
Таким образом, для запроса об определенной дате доступное время площадки для бадминтона можно изменить на
GET /sports/badminton/20220105?status=idle HTTP/1.1
[various other headers]
HTTP определяет GET как безопасную операцию, что означает, что она не вносит никаких изменений в состояние. Таким образом, мы можем вызывать GET любое количество раз и каждый раз получать один и тот же результат. Интернет также кэширует запросы и результаты GET, что является ключевым фактором в том, насколько хорошо работает веб-архитектура.
Результат тот же, и тогда мы бронируем период времени.
POST /reservations/987654321 HTTP/1.1
[various other headers]
Запрос не меняется, но возвращается. Если все пойдет хорошо, сервис вернет код ответа 201, указывающий, что новый ресурс создан.
HTTP/1.1 201 Created
Location: orders/abcd987654321
[various headers]
{
"orderId": "abcd987654321"
}
Ответ 201 также включает атрибут Location, указывающий, что клиент может использовать URL-адрес этого атрибута для получения последнего статуса ресурса заказа.
Если произошла ошибка, например, кто-то другой забронировал слот, то:
HTTP/1.1 409 Conflict
[various headers]
{
"error": "该时间段已被预定"
}
Важной частью этого ответа является использование правильного кода ответа HTTP, чтобы указать, что пошло не так. В этом сценарии 409 — хороший выбор, чтобы указать, что кто-то другой обновил ресурс взаимоисключающим образом. На уровне 2 мы явно используем некоторый тип ответа об ошибке вместо кода возврата 200, но включаем ответ об ошибке.
Уровень 3: ХАТЕОАС
HATEOAS (Hypertext As The Engine Of Application State), переводится на китайский язык как «Гипертекст как механизм состояния приложения», ядром этого описания является концепция гипермедиа, другими словами: идея ссылок.
Из запроса уровня 2:
GET /sports/badminton/20220105?status=idle HTTP/1.1
[various other headers]
Возвращаемая информация отличается от Level2
HTTP/1.1 200 OK
[various headers]
{
"times": [
{
"start": "1400",
"end": "1600",
"id": "123456789",
"link": "/reservations/123456789"
},
{
"start": "1700",
"end": "1830",
"id": "987654321",
"link": "/reservations/987654321"
}
]
}
Каждый временной интервал теперь имеет элемент ссылки, который содержит URI, сообщающий нам, как записаться на прием. Смысл управления гипермедиа состоит в том, чтобы сообщить нам, что мы можем делать дальше, и указать URI ресурса, с которым нам нужно работать. Нам не нужно знать, куда направляется запрос о встрече, элементы управления гипермедиа в ответе подскажут нам, что делать.
Запрос на резервирование по-прежнему использует уровень 2
POST /reservations/987654321 HTTP/1.1
[various other headers]
Ответ содержит ряд элементов управления гипермедиа для различных дальнейших действий.
HTTP/1.1 201 Created
Location: orders/abcd987654321
[various headers]
{
"orderId": "abcd987654321",
"link": {
"rel": "delete",
"uri": "/orders/abcd987654321"
}
}
Возврат обеспечивает, как отменить заказ.
Restful API уровня 3 приносит большое удобство пользователю.Пользователю нужно только знать, как получить запись ресурса.Каждый последующий URI можно получить через запрос.Если его нельзя получить, значит, запрос не может быть получен. быть казненным.
Недостатки RESTful
Следует подчеркнуть, что,RESTful — это не спецификация, это стиль, это не обязательно. Поэтому стиль неопределенный, отец сказал, что публика разумна, а мать сказала, что мать разумна. Даже RESTful, разработанный программистами одного уровня, трудно быть одинаковым. В команде разработчиков самое табу не единообразие!
1. RESTful ориентирован на ресурсы, поэтому все интерфейсы — это существительные, особенно существительные во множественном числе. Простой CRUD по-прежнему подходит, но большую часть бизнес-логики трудно абстрагировать в ресурсы. Например, вход/выход из системы не является ресурсом, если он абстрагируется как создание сеанса/удаление сеанса. Это не только нелогично, но и противоречит идее RESTful.
2. RESTful обеспечивает только базовые добавления, удаления, модификации и проверки.Нет решения для сложной логики, такой как пакетная загрузка и пакетное удаление. Для сложных запросов запуск невозможен. И будет много вариантов при разработке, использовать PUT или PETCH для изменения ресурсов? Использовать параметры запроса или тело?
3. Проблема кодов ошибок еще сложнее, RESTful рекомендует использовать код состояния в качестве кода ошибки для унификации. В реальной разработке существует бесчисленное множество значений бизнес-логики, которые трудно унифицировать. Например, указывает ли код состояния 400 на то, что возникла проблема с передачей параметров или ресурс был занят. 404 означает, что интерфейс не существует или ресурс не существует.
В конце концов, время и силы разработчиков тратятся не на то, как реализовать эту логику, а запутываются в том, в каком ресурсе эта логика? Впустую потраченное время и в итоге получился невзрачный "RESTful" API.
Самый важный момент заключается в том, что нет никакой разницы между RESTful и RPC., Все спецификации кода, дизайн интерфейса и различные регламенты на самом деле должны формировать консенсус внутри команды и предотвращать путаницу, вызванную различиями в личных привычках. Напротив, спецификация JSON-RPC относительно проста и удобна в использовании.
Даже если команда оговаривает, что URL должен быть представлен действием, а все запросы должны использовать POST, это не проблема.
Так что, будь то RESTful или RPC, в конечном счете, это для разработчиков и служб приложений продукта.Если это может принести удобство и уменьшить путаницу, его стоит использовать; наоборот, если это приносит больше проблем, чем нужно решить , то дак Не надо.
конец
В первые два года из-за отсутствия опыта я высказывал некоторые мнения, которые считал правильными, а теперь, если подумать, я слишком молод🤭. Есть поговорка, которая верна: чем больше узнаешь, тем больше невежественным вы себя чувствуете.
Это не просто создать, пожалуйста, переместите палец и поднимите палец вверх.
Больше статей, пожалуйста, переместитеГитхаб арендодателя, Если вам это нравится, пожалуйста, нажмите звездочку, это также поощрение автора.