campus:core — пример библиотеки для реализации API в системе с унаследованным кодом

Здравствуйте коллеги!
Хочу представить вашему вниманию проект, который родился во время работы над системой информатизации КПИ. Достаточно давно в этом научном заведении идут работы по автоматизации деятельности различных его подразделений. О том, что было сделано, делается и планируется реализовать в рамках этого проекта — читайте под катом.

Я пишу диссертацию, поэтому со своим университетом после выпуска я не только не попрощался — но и продолжаю участвовать в некоторых проектах, которые в нем реализуются. Сейчас одним из таких проектов является информационная система, которая позволила бы объединить различные сервисы и программное обеспечение. Поскольку программного обеспечения и наработок имеется очень и очень много, при проектировании такой системы потребовалось разработать архитектуру, которая была бы достаточно гибкая чтобы одновременно позволить взаимодействовать как унаследованному ПО так и новому.
Разработка большей части ПО для ниверситета производится в конструкторском бюро «Информационных систем» ^[1] подразделении которое начинчает свою историю с 1988 года. Одной из особенностей КБ является то, что участие в разработках принимают студенты ВУЗа. Сама по себе эта практика полезна и хороша — ребята получают свой первый практический опыт участвуя в реальных проектах. Но есть и другая сторона медали — многие из ребят еще не умеют писать хороший, правильный, надежный и читаемый код. Это в общем-то и не удивительно — ведь они только учатся.

В основу системы был положен REST подход. Все модули и сервисы должны будут взаимодействовать через единый API, который будет прослойкой между различными частями системы. Отдельные части API было решено отдать на разработку некоторым из студентов.

Для того, что бы результат облегчить им задача и результат их работы не пропал даром ядро API было разработано таким образом, чтобы максимально облегчить процесс расширения API и дать простые и удобные возможности для отладки.

Что же представляет собой campus:core и что предлагает?

1. Интроспекция контроллеров
2. Обработка исключений
3. Единый контейнер передачи данных
4. Поддержка пейджинга
5. Логирование событий

▌Интроспекция контроллеров

Интроспекция позволяет
Во-первых: облегчить отладку кода для разработчика
Во-вторых: предоставить инструмент для отладки (API Scaffolder).

▌Единый контейнер передачи данных

Ответы API передаются в формате JSON. При этом каждый ответ инкапсулирован в «контейнер» следующего вида:

• StatusCode – код операции. Соответствует HTTP кодам.
• TimeStamp – штамп времени, когда сервер отдал результат запроса.
• Paging – информация о постраничном разбиении информции. Используется в те случаях, когда необходимо отдавать большие списки.
  • PageCount – общее количество страниц
  • TotalItemCount – общее количество элементов
  • PageNumber – номер текущей страницы
  • PageSize – размер страницы (количество элементов на странице)
  • HasPreviousPage – есть ли предыдущая страница после текущей страницы
  • HasNextPage – есть ли следующая страница после текущей страницы
  • IsFirstPage – является ли текущая страница первой
  • IsLastPage – является ли текущая страница последней
  • FirstItemOnPage – значение ключевого поля первого элемента на странице
  • LastItemOnPage – значение ключевого поля последнего элемента на странице

• Data – непосредственный результат работы метода в JSON формате.

▌Обработка исключений

Всегда на стороне клиента можно сделать обработке, который будет знать об успешности выполнения любого запроса.
Исключена возможность выпадения «голого» exception даже в том случае, если разработчик не обратила ошибку у себя.
Каждая операция имеет уникальный uid, что помогает в отладке.

▌Поддержка пейджинга

Поддержка пейджинга реализована на основе библиотеки X.PagedList. К слову, X.PagedList — это форк популярной библиотеки PagedList, который был сделан после того, как Трой приостановил поддержку проекта ^[2]. Сейчас X.PagedList в отличие от своей предшественницы доступна не только для десктопных, серверных и веб-приложений, но и для устройств на под управлением Windows Phone и приложений на Silverlight.
Ознакомиться с проектом можно здесь — github.com/ernado-x/X.PagedList ^[3].
Проект также доступен в репозитории NuGet — www.nuget.org/packages/X.PagedList ^[4]
Что касается использования пейджинга, то реализовано все достаточно просто:

public Result GetPagedData(int rows, int page, int size)
        {
            var list = new List<Object>();

            for (var i = 0; i < rows; i++)
            {
                list.Add(new
                {
                    Id = i,
                    Value1 = "val1 = " + i,
                    Value2 = "val2 = " + i * i
                });
            }

            var result = list.ToPagedList(page, size);

            return Result(result);
        }

Когда метод Result получает обеъкт типа IPagedList, то автиматически заполняет поле Paging контейнера.

▌Логирование событий

Для облегчения отладки API базовый контроллер реализует возможности, которые помогут центарлизированно отслеживать все запросы к API:

Campus.Core.ApiController.ExceptionHandled += ApiController_ExceptionHandled;
Campus.Core.ApiController.ResultExecuted += ApiController_ResultExecuted;

В данном примере, при обработке любого запроса будет вызываться метод ApiController_ResultExecuted.
В случае возникновения исключительно ситуации — ApiController_ResultExecuted.

▌Ресурсы

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

Пример реализации веб-приложения на базе campus:core и Web API доступен на GitHub: github.com/DOIS/campus.core/tree/web-api/Example ^[5].

▌GitHub

• Версия на основе ASP.NET MVC 5 версия — github.com/DOIS/campus.core ^[6]
• Версия на основе ASP.NET Web API — github.com/DOIS/campus.core/tree/web-api ^[7]

▌NuGet

• Стабильная версия (ASP.NET MVC 5) — www.nuget.org/packages/campus.core/1.0.8.235 ^[8]
• Бета-версия (ASP.NET MVC 5) — www.nuget.org/packages/campus.core/2.0.0.750-beta ^[9]

▌Дальнейшая судьба проекта

На данный момент я начал перевод ядра API с ASP.NET MVC на ASP.NET Web API. Соответственно часть кода campus:core также была переписана. Эта версия уже также доступна в NuGet, но пока находится в стадии бетатестирования.
Сама же библиотека сейчас используется не только в различных проектах разрабатывающихся в конструкторском бюро и НТУУ КПИ но и в других компаниях. Так, на данный момент, campus:core используется группой компаний Рост, коалиционной программой лояльности чудоcard, проектом Торф ТВ, и другими.

Автор: Ernado

Источник ^[10]