Today I have started development of new package for Golang-developers – Go-Up. I made it because I have noticed that I should repeat some things with each new project on Golang, so the main purpose of Go-Up package is to simplify building of new Golang applications.
This is a beginning so I just want to share link to GitHub here – https://github.com/ildarusmanov/go-up
Возникла у нас в компании проблема с превью документов, использовали мы для превью на портале всем известную тулзу от гугла. Но с ней были проблемы, у пользователя не всегда рендерился документ(видимо лимиты по количеству вызовов) и когда он рендерился, то бывало, что внешне превьюсильно отлиалосьот оригинала. Поэтому было решено разработать превью документов на нашем кор. портале с использованием уже имеющегося у нас Office Online.
По счастливому стечению обстоятельств для работы с документами в Office Online используется неплохо задокументированный протокол – WOPI (http://wopi.readthedocs.io/).
Что нам нужно реализовать для организации предпросмотра:
1) Нужно получить необходимые для обращения к Office Online данные:
– файл discovery.xml
– ссылка на файл /wopi/<fileId> и ссылка на действие офис онлайн из файла discovery.xml
– токен и время его жизни в виде таймстемпа в миллисекундах
2) Нужно написать реализацию метода CheckFileInfo, который будет возращать информацию о файле
3) Нужно написать реализацию метода GetFile, который будет возращать содержимое файла
Лучше слов расскажет код, шутка, на самом деле мне пока немного лень писать то, как это было реализовано 🙂
Но надеюсь, что и этот код сможет оказаться полезным.
Сегодня хочу рассказать о некоторых своих размышлениях по поводу TDD в этой небольшой заметке.
Первое, что такое TDD? Wiki говорит нам следующее(https://ru.wikipedia.org/wiki/%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0_%D1%87%D0%B5%D1%80%D0%B5%D0%B7_%D1%82%D0%B5%D1%81%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5):
Разработка через тестирование (англ. test-driven development, TDD) — техника разработки программного обеспечения, которая основывается на повторении очень коротких циклов разработки: сначала пишется тест, покрывающий желаемое изменение, затем пишется код, который позволит пройти тест, и под конец проводится рефакторинг нового кода к соответствующим стандартам. Кент Бек, считающийся изобретателем этой техники, утверждал в 2003 году, что разработка через тестирование поощряет простой дизайн и внушает уверенность (англ. inspires confidence).
Кстати, рекомендую прочитать книгу о TDD самого Кента Бега(http://www.ozon.ru/context/detail/id/1501671/). О том для чего и когда использовать TDD я в этой заметке писать не буду, т.к. я думаю, что это достаточно очевидный момент и как правило вопрос возникает как к этому подходу разработки перейти и как его успешно внедрять.
Ниже на рисунке представлен процесс разработки программы в стиле TDD.
Начинается весь процесс всегда с написания тестов и далее двигаемся по стрелочке:
1. Написание теста, без написания логики программы, которую мы проверяем в тесте.
2. Запуск теста и проверка того, что тест красный, т.к. у нас нет реализации тестируемой части(если тесты зеленые – значит тесты ничего не проверяют и их нужно переписать)
3. Пишем код, который делает тесты зелеными(минимальный код, а точнее любой корректно работающий код, который сделает тесты зелеными)
4. Запускаем тесты и проверяем, что они зеленые
5. Рефакторинг, мы переписываем наш "говнокод" для озеленения тестов, так, чтобы он был работающим и хорошо пахнущим не только для тестов, но и для нас.
Исходя из собственной практики на первых этапах самое сложное это начать писать первый тест, до реализации тестируемого кода и здесь я вижу два приема:
1. Написать сначала интерфейс, затем переходить к тесту. Это позволит начать переход к TDD и при этом не слишком "тупить" над тем, что и как тестировать, т.к. часть кода вы уже будете писать до теста и в голове уже будет небольшое понимание того, что тестировать. Ну а как привыкните – начнете писать тесты сразу.
2. Это писать сначала самый короткий, т.е. минимальный и общий тест. Собственно это и есть праведный путь TDD. Таким образом дизайн программы будет строиться по циклу через тесты, с каждой итерацией вы будете добавлять тесты и код.
Часто такое бывает, что есть желание перевести проект на TDD и жить хорошо, но оказывается так, что текущая ситуация с дизайном не позволяет перевести весь проект на TDD, на практике иногда ине всегда возможно в разумные сроки перенести весь проект на TDD. В связи сэтим разумно этого не делать, но естьвсе таки несколько вариантов для того, чтобы начать использовать TDD и в таком проекте:
1. Писать проект заново, особенно если в пользу этого уже есть какие-нибудь и другие предпосылки.
2. Выделять из проекта отдельные компоненты и тестировать их. Этот вариант подходит для проектов с не слишком НЕудачным дизайном.
3. Использовать TDD только для новых изменений кода и со временем весь проект сможет перейти на TDD. Этот вариант на мой взгляд самый универсальный.
В общем и в целом считаю, что TDD это хороший способ улучшить стабильность и надежность своего кода и даже при написании небольших приложений это позволяет снизить количество ошибок в приложении многократно. Как минимум это стоит попробовать.
Одним из самых распространенных подходов при проектировании API является REST API, что такое REST API можно узнать здесь.
Я же хочу рассказать о тех принципах, которые помогут сделать ваш API удобным для других разработчиков, т.е. для ваших клиентов.
Перейдем к принципам, поскольку для REST используется протокол HTTP, то он силньо завязан на его особенностях и в частности на адресе URL.
Чтобы ваш API было легче понимать уделите особое внимание идентификаторам ваших ресурсов(URI):
Всегда обрабатывайте ошибки и сообщайте о них клиенту, используйте соответствующие коды статуса ответа HTTP, также сопровождайте ошибки описанием в теле ответа, возвращайте внятное текстовое описание ошибки.
Всегда версионизируйте API, например с помощью префикса /v1 или в заголовках и поддерживайте как минимум две последнии версии. Это позволит вашим клиентам плавно и без проблем переходить на новые версии вашего API.
Испольуйте для пагинации параметры limit и offset, не забывайте возвращать в ответе общее количество доступных ресурсов.
Клиентам не всегда нужны все доступные поля, потому предусмотрите возможность кастомизации списка возвращаемых полей параметром fields.
Параметр fields может содержать одно и более названий полей, перечисленных через запятую, эта возможность бывает полезной для сложных ресурсов с большим количеством метаданных.
Выделите для вашего API отдельный субдомен(например api.example.com/v{version_id}) и сосредоточьте все ваше API в зоне этого субдомена.
Для передачи формата входных и получаемых данных указывайте формат в виде расширения файла(например /v1/videos.json) и обеспечьте поддержку нескольких форматов данных.
Напишите SDK или библиотеки для платформ, которые используют ваши клиенты. Cопроводите это все качественными и подробными примерами использования вашего API и документацией по использованию ваших инструментов и API.
