предисловие
С быстрым развитием Интернета цикл разработки проектов компании постоянно сокращался.Мы сталкиваемся с различными потребностями и используем оригинальный метод стыковки.Каждой стороне сложно быстро реагировать на различные потребности, и еще труднее улучшить эффективность. Поэтому нам пришлось переформулировать спецификацию дока и разработать логику для быстрого запуска проекта.
Наша цель
Минимизируйте затраты на общение, проводите меньше встреч и решайте большинство проблем.
Тратьте минимум времени на написание документации и убедитесь, что 90% разработчиков все понимают.
Даже если вы не читаете документацию, вы можете знать все виды логики интерфейса.
Не переписывайте код
Пишите максимально читаемый код
что мы наделали
Полное разделение спереди и задних концов
Android, ios, веб используют набор интерфейсов
Унифицированная спецификация интерфейса (опубликовать, поставить, получить, исправить, удалить)
Унифицированные инструменты отладки
Документация по единому интерфейсу
перед нами
Интерфейс выглядит так:
Запрос клиента такой:
…/Aproject/module1/getProducts?id=1&a=2&b=3&c=4&d=5…………
Страница A ====="Страница B (содержащая n переменных) ===="Страница C (содержащая m переменных, включая i переменных страницы A) ------- часто n>4
Большая часть запросов POST.Что за хрень ставить,патчить,удалять - это не мое дело.
Что касается использования json для входных параметров интерфейса, то это полностью зависит от настроения разработчиков.
Вывод такой:
{"сообщение":"успех","код":0,"данные":конкретный контент}
Массив, содержащийся в данных, может быть [{"a":"1","b":"1"},{"a":"1","b":"1"},{"a":" 1","b":"1"},{"a":"1","b":"1"}] не будет использовать идентификатор, даже если он используется на следующей странице, но пропустит все поля в . В интерфейсе A используйте product, чтобы вернуть продукт; в интерфейсе B используйте good, и несколько интерфейсов, вероятно, будут несогласованными.
Стыковка клиента похож на это:
Один набор для Android и ios, один набор для некоторых интерфейсов, один набор для HTML5.
Клиент и фон постоянно общаются
Документация по интерфейсу такая
swagger
рэп Али
Документ Word
разное
Конечно, я считаю артефакты Swagger и RAP очень мощными и позволяют добиться различной функциональной логики, но учитывая, что разработчики разве что, сложность высока, повысить эффективность сложно, я решил не использовать эти два артефакта на начальном этапе. .
Задняя часть вот такая
.../Проект/модуль1/getProducts ---- интерфейс
.../Проект/Module1/Products.html ---- страница
.../Проект/модуль1/Products.js ---- статические ресурсы
Интерфейсы и статические ресурсы переплетаются, ведь много страниц может разрабатываться одним разработчиком одновременно, минус здесь в том, что нужно только самому разбираться в логике. Как только коллега уйдет, много неясной логики останется для будущих поколений.
и т.д…………
рефакторинг
Давайте углубимся в тему и поговорим о том, как я переформулировал процесс перед лицом многих из вышеперечисленных проблем.
соглашения о базе данных
Согласовано, что все таблицы в базе данных должны содержать поле первичного ключа с именем id. Некоторые люди могут сказать, что обычно не должен быть первичный ключ id в каждой таблице? Однако из-за вялой разработки в нашем проекте некоторые таблицы не имеют первичного ключа id или первичного ключа, который не является id. Здесь мы используем распределенный глобальный уникальный код в качестве идентификатора.
соглашение о выводе API
Условлено, что все исходящие параметры содержат список, и другие запросы будут использовать эту группу списков, тогда все объекты в списке должны содержать уникальный идентификатор.
соглашение о входе
Согласовано, что аутентификация идентификатора токена единообразно проходит в режиме параметров, а серверная часть использует программирование аспекта aop для идентификации идентификатора пользователя. Остальные параметры всегда json.
результирующее соглашение об интерфейсе
- GET: соответствует операции извлечения (операции запроса)
- POST: соответствует операции Create
- УДАЛИТЬ: соответствует операции Удалить
- Поместите: Операция обновления, соответствующая
- ИСПРАВЛЕНИЕ: Соответствующее действие обновления
Сначала мы выбираем существительное во множественном числе, например продукт
почтовый метод
Добавить ХХХ
Например.../продукты
Это означает, что входной параметр нового продукта json выглядит следующим образом:
{
"name":"我是一款新产品",
"price":100,
"kind":"我的分类",
"pic":[一组图片],
//等等还有很多
}
Уровень управления кодом Java
@ResponseBody
@RequestMapping(value = "/A项目/B模块/products", method = {RequestMethod.POST})
public ResultObject getProducts() {
//具体逻辑。
}
метод PUT
Обновить запись XXX
Например.../продукты/1111111111
Входной json выглядит следующим образом:
{
"name":"我是一款新产品",
"price":100,
"kind":"我的分类",
"pic":[一组图片],
//等等还有很多
}
Указывает на обновление записи с 1111111111id
уровень управления кодом Java
@ResponseBody
@RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.PUT})
public ResultObject putProducts(@PathVariable(value = "id") String id) {
//具体逻辑。
}
получить метод
Получить все ХХХ
.../products означает получить все продукты
Из-за подкачки мы добавили ?page=1&pageSize=50
Мы договорились, что все существительные во множественном числе будут возвращать список, и каждый объект списка имеет уникальный идентификатор с идентификатором поля.
Например
{
"data":{"list":[{"id":"唯一id","其他很多字段":""},{"id":"唯一id","其他很多字段":""}],"page":1,其他字段},
"code":0,
"message":"成功"
}
.../products/{id} для получения определенного продукта (должен быть более подробным, чем список)
Например, в конкретном продукте также содержится список, например, рекомендуемый список продуктов, то: ...... / Products / {Id} / Рекомендации
Предположим, что он содержит не список, а объект, например информацию о комиссии товара, тогда: .../products/{id}/Commission
Здесь мы судим, является ли это объектом или списком, по тому, стоит ли существительное во множественном числе.
уровень управления кодом Java
@ResponseBody
@RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.GET})
public ResultObject putProducts(@PathVariable(value = "id") String id) {
//具体逻辑。
}
патч метод
Обновить информацию о локальном продукте XXX YYY
Входные параметры являются подмножеством входных параметров метода post. Будут объяснены все параметры, которые поддерживают обновление, но не все переменные поддерживаются.
.../продукты/{id}
{
"name":"我是一款新产品",
"price":100,
//部分变量
}
уровень управления кодом Java
@ResponseBody
@RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.PATCH})
public ResultObject putProducts(@PathVariable(value = "id") String id) {
//具体逻辑。
}
метод удаления
Удалить записи XXX
…/продукты/11111
Удалить 11111 товаров.
уровень управления кодом Java
@ResponseBody
@RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.DELETE})
public ResultObject putProducts(@PathVariable(value = "id") String id) {
//具体逻辑。
}
другие инструкции
Мы используем глаголы как можно реже, но есть некоторые действия, требующие глаголов, например вход в систему. Что касается номера версии, мы намерены добавить /v1/ и т. д. после модуля.
Разрешительное соглашение
Сервер - определить роль пользователя, есть ли разрешение на выполнение логики.
Соглашение о разделении внешнего и внутреннего интерфейса
Серверная часть в основном основана на интерфейсе разработки и больше не участвует в разработке страницы или разработке гибридной jsp-страницы, которая возвращается в виде интерфейса, а передняя часть использует js для рендеринга данных и логики обработки.
Общий интерфейс
Веб, Android и ios используют унифицированный интерфейс не из-за особых требований какой стороны требуются дополнительные открытые интерфейсы.
Используйте унифицированный инструмент создания слоев dao
На основе mybatis-generator он трансформируется в слой dao и некоторые сервисные слои, подходящие для нашего проекта, которые совместно поддерживаются и используются внутри.
Используйте почтальон как самый интерфейсный документ и инструмент отладки
Хотя рэп и чванство, описанное выше, оба являются отличными интерфейсными артефактами, мы все же выбираем почтальон.Разработчики хранят имя интерфейса, описание, входные параметры, выходные параметры и различные выходные параметры, чтобы можно было вести разработку напрямую.Вы можете видеть смысл интерфейса понятен.
Мы рекомендуем использовать плагин для браузера, в качестве примера мы возьмем 360 Speed Browser. Адрес загрузки плагина:
https://download.csdn.net/download/qq273681448/10033456
Откройте центр расширений браузера 360, затем проверьте режим разработчика, затем нажмите, чтобы загрузить распакованное расширение, выберите распакованный каталог сжатого пакета и, наконец, нажмите, чтобы запустить.
Среди них в тестах пишутся комментарии к параметрам и описания интерфейсов:
/*
这里是接口说明，和每个出参、入参的意思。
*/
Интерфейсы разбиты на папки по модулям:
Входные параметры:
Пример вывода:
Обычный запрос:
Разработчики могут непосредственно видеть пример интерфейса для разработки, а при разработке разработчики могут сохранить его как файл postman, вызвав его один раз.Чтобы ускорить запуск, мы разрешаем код (включая комментарии), определяемый переменными класса сущности в java, который нужно скопировать напрямую. Вставьте его.
js и другие проблемы с кешированием статических ресурсов
В краткосрочной перспективе мое требование состоит в том, чтобы уменьшить количество изменений в js-файлах, а если есть изменения, обязательно изменить номер версии. Итак, как уменьшить модификацию, наш подход заключается в том, чтобы написать часть js в html. В любом случае, передняя и задняя части разделены, и большое дело в том, чтобы обновить кеш узла cdn. В конце концов, большинство браузеров не будут активно кешировать html-файлы (большинство браузеров кэшируют документы js и т. д.).
Единая структура запросов js
Здесь мы используем структуру запроса angular js, потому что мы используем больше angularjs внутри и лучше знакомы с ним Инкапсулированный запрос может автоматически выводить запрос об ошибке и переписывать обратный вызов ошибки.
Текущий эффект
В настоящее время, когда наш клиент видит интерфейс, мы, вероятно, можем сказать его значение, а также можем угадать значение ряда интерфейсов, таких как
.../классы
Видно, что это интерфейс для получения списка классов,
предполагать
……/classes/id get Получить сведения о классе, чей идентификатор равен id
....../classes/id patch изменяет информацию о классе
……/classes/id удалить удалить информацию о классе
Что касается входных параметров, patch является подмножеством post, put=patch, delete не имеет входных параметров.
Что касается значения входных параметров, вы можете напрямую открыть почтальон, чтобы напрямую просмотреть значение каждого поля, и вы можете вызывать данные среды разработки (компьютеры, не являющиеся разработчиками) в режиме реального времени.Здесь мы используем несколько сред.Для получения подробной информации вы можете учиться:
Внешний интерфейс использует унифицированную инкапсулированную структуру запросов js, чтобы ускорить процесс разработки без создания колес.
Разработчики, обычно занимающиеся разработкой и написанием кода, используют postman для самотестирования, после завершения теста также пишется интерфейсный документ.
Тестировщики, которые хотят разобраться в документации по интерфейсу, также могут напрямую использовать postman для их импорта и просмотра.
На данный момент наши расходы на связь снизились более чем вдвое, а оставшееся содержание встречи — декомпозиция требований в соответствии с пользовательским интерфейсом или построение в соответствии с пользовательским интерфейсом.
Суммировать
После долгих метаний прогресс разработки, наконец, немного ускорился, и в определенной степени был достигнут эффект быстрого запуска проекта. У каждого есть свое мнение об API спокойного стиля.Пока внутренние соглашения ясны и общение может быть сокращено как можно меньше, я думаю, что это хорошее понимание. Что касается инструментов интерфейса, то многие могут сказать, почему не используют предыдущие, я думаю, что они будут использоваться в будущем. аннотации относительно строгие.Не торопитесь.В конце концов, мы будем следить.Впереди еще долгий путь.