ddrv-test/firmapi-webapi

operation-bl (chtob nikto ne dogadalsya)

0.9.5 2017-12-21 06:46 UTC

README

Приложение состоит из двух частей:

  1. fortwogis/core - непосредственно АПИ. Его можно подключить к любому PHP-приложению и использовать напрямую (без http-запросов)
  2. fortwogis/webapi - веб-интерфейс для первого приложения

Я разделил их в целях упрощения интеграции с другими сервисами.

Требования

Для работы приложения необходимо:

  • Сервер БД mysql
  • php версии не ниже 5.3
  • расширение php pdo
  • расширение php pdo_mysql

Установка

Для установки нужно перейти в директорию c проектами и выполнить команду

cd /path/to/projects
composer create-project fortwogis/webapi

Проект будет располагаться в директории /path/to/projects/webapi

Настройка

Веб-сервер

Необходимо настроить вебсервер. Директива DOCUMENT_ROOT должна быть /path/to/projects/webapi/public_html

Все запросы должны обрабатываться файлом /path/to/projects/webapi/public_html/index.php

Для работы с веб-сервером apache необходим модуль mod_rewrite. Остальное сделает файл /path/to/projects/webapi/public_html/.htaccess

Для примера, настройка nginx. АПИ будет в корне домена.

server {
    listen 80;
    server_name your.site;
    root  /path/to/projects/webapi/public_html;
    access_log /var/log/nginx/access.log;

    index index.php;

    location / {
        try_files @php @php;
    }

    location @php {
        proxy_cache_bypass 1;
        proxy_no_cache 1;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_ignore_client_abort on;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Приложение

Все настройки по умолчанию хранятся в файле /path/to/projects/webapi/vendor/fortwogis/core/config/default.php Редактировать этот файл не желательно. Все настройки можно указать в файле /path/to/projects/webapi/config/config.php

return array(
    /** Токены, расширяющие доступ к методам АПИ. 
     * Публичные методы настраиваются в файле /path/to/projects/webapi/vendor/fortwogis/core/config/default.php
     * в секции ['tokens']['*']
     */
    'tokens' => array( 
        '43jkh932yhsa2ef8ySEsfFask43isrR3' => array( // Токен для доступа ко всем методам
            '*' => array('*'),
        ),
        'a2efFh932y8yxs43jkSEs3kfxtrR43is' => array( // Токен для доступа к методу company.addPhones и company.removePhones
            'company' => array(
                'addPhones',
                'removePhones',
            ),
        ),
    ),
    /**
     * Соединения яс базами данных
     */
    'connections' => array(
        'db1' => array(
            'type' => 'mysql',
            'host' => 'localhost',
            'port' => '3306',
            'name' => 'dataaseName',
            'user' => 'userOfDatabase',
            'pass' => 'password',
            'char' => 'UTF8',
        ),
    ),
);
/**
 * В принципе, этих настроек должно быть достаточно
 */

Импорт данных

Структура

Для создания структуры БД, выполните запросы и файла /path/to/projects/webapi/data/structure/{REPOSITORY}/{DB} , где {REPOSITORY} - имя сущности, а {DB} - тип базы данных

Данные

Для импорта тестовых данных выполните команду

php /path/to/projects/webapi/run/import.php

Этот скрипт создаёт в БД 100 улиц по 100 зданий. В каждом здании по 10 фирм. Названия улиц генерируются из слогов. Номера зданий по порядку (иногда добавляя корпуса к номеру здания в виде 10/1 или 10к1.) Улицы расположены вдоль меридиан и равноудалены друг от друга (ну почти равноудалены, земля же вроде как круглая). Здания по одной улице равноудалены друг от друга. Область разброса зданий - от 55.029312,82.893994 до 55.078388,82.995618

Названия и струтура рубрик жёстко прописана в файле import.php

Названия фирм - слово Фирма + порядковый номер

Количество телефонов фирмы - случайное (от 1 до 5), телефоны генерируются случайно

Рубрики к фирмам привязываются случайно (от 1 до 5).

Использование

Теперь АПИ готово к использованию. (Не забудьте перезапустить веб-сервер для применения настроек)

Доступные методы

build.add

Параметр Обязательный Описание
street + Название улицы
number + Номер здания
latitude + Координата широта
longitude + Координата долгота

build.get

Параметр Обязательный Описание
ids - ID зданий. Перечисляются через запятую
street - Название улицы
number - Номер здания
offset - Смещение выборки
count - Количество возвращаемых зданий

company.add

Параметр Обязательный Описание
build + ID здания
name + Название фирмы

company.addPhones

Параметр Обязательный Описание
company + ID фирмы
phones + Номера телефона. Перечилсяются через запятую

company.addRubrics

Параметр Обязательный Описание
company + ID фирмы
rubrics + ID рубрик. Перечилсяются через запятую

company.getAround

Параметр Обязательный Описание
latitude + Широта точки
longitude + Долгота точки
radius + Радиус поиска в метрах
offset - Смещение в выборке
count - Количество возвращаемых фирм

company.getByAddress

Параметр Обязательный Описание
street + Название улицы
number + Номер здания
offset - Смещение в выборке
count - Количество возвращаемых фирм

company.getByBuildId

Параметр Обязательный Описание
id + ID зданий. Разделяются запятой
offset - Смещение в выборке
count - Количество возвращаемых фирм

company.getById

Параметр Обязательный Описание
id + ID фирм. Разделяются запятой
offset - Смещение в выборке
count - Количество возвращаемых фирм

company.getInRectangle

Параметр Обязательный Описание
latitude + Самая северная координата области поиска (Широта)
longitude + Самая западная координата области поиска (Долгота)
width + Ширина области поиска в метрах
height + Высота области поиска в метрах
offset - Смещение в выборке
count - Количество возвращаемых фирм

company.removePhones

Параметр Обязательный Описание
company + ID фирмы
phones + Номера телефона. Перечилсяются через запятую

company.removeRubrics

Параметр Обязательный Описание
company + ID фирмы
rubrics + ID рубрик. Перечилсяются через запятую

help.main

Без параметров

rubric.add

Параметр Обязательный Описание
name + Название рубрики. Допускаются символы латинского и русского алфавита, цифры и пробел
parent - ID родительской рубрики

Так же доступные методы и их параметры можно посмотреть по адресу

http://your.site/help.main?token=43jkh932yhsa2ef8ySEsfFask43isrR3

Этот метод вернёт json-объект вида

{
  "result": "true",
  "data": {
    "help.main": {
      "description": "Помощь",
      "params": []
    },
    "company.getById": {
      "description": "Поиск фирм по ID",
      "params": {
        "id": {
          "type": "string",
          "required": true,
          "description": "ID фирм. Разделяются запятой"
        },
        "offset": {
          "type": "integer",
          "required": false,
          "default": 0,
          "minimal": 0,
          "description": "Смещение в выборке"
        },
        "count": {
          "type": "integer",
          "required": false,
          "default": 100,
          "minimal": 1,
          "maximal": 100,
          "description": "Количество возвращаемых фирм"
        }
      }
    }
  }
}

О разработке

Проектирование базы данных

Таблицы баз данных не имеют между собой прямой связи. Это позволит в будующем для некоторых сущностей сменить СУБД без вмешательств в само приложение (нужно будет просто изменить в конфиге обёртку для работы с данными). За обеспечие целостности данных будет отвечать код. Этот подход проиграет по времени выполнения скрипта, но решает проблему масштабирования и перехода с одной БД на другую (Причём можно переносить на другую СУБД не все данные, а, к примеру, только рубрики).

Работа с данными

Работа с данными осуществляется через обёртку. Обертка должна наследовать абстрактный класс базы данных Fortwogis\Core\Repository\DATABASE_TYPE и интерфейс Fortwogis\Core\Repository. Некоторые репозитории в связи со спецификой, имеют свой интерфейс (например, Rubric) Этот интерфейс содержит методы поиска по фильтрам, удаление по фильтрам, изменение по фильтрам и сохранение записи. Вся работа с данными должна осуществляться именно через эти методы. В таком случае можно будет написать обёртку под любой источник данных (SQL СУБД, NoSQL СУБД), файловое хранилище, АПИ других систем и т.д.). Это позволит достаточно быстро переключиться с одного типа БД на другой.

Структура приложения

Рассмотрим основное - библиотека fortwogis/core

/path/to/projects/webapi/vendor/fortwogis/core/
    config/ - конфиги
        default.php - конфигурация приложения по умолчанию
    src/ - кодовая база приложения
        Object/ - Классы объектов
            Build.php - Класс Объекта "Здание"
            Company.php - Класс Объекта "Фирма"
            Help.php - Класс Объекта "Помощь"
            Rubric.php - Класс Объекта "Рубрика"
        Repository/ - Обёртки для работы с данными
            Build/ - Обёртки для работы с данными типа Build
                Mysql.php - Обёртка для работы с данными типа Build в базе данных Mysql
            Catalog/ - Обёртки для работы с данными типа Catalog
                Mysql.php - Обёртка для работы с данными типа Catalog в базе данных Mysql
            Company - Обёртки для работы с данными типа Company
                Mysql.php - Обёртка для работы с данными типа Company в базе данных Mysql
            Phone - Обёртки для работы с данными типа Phone
                Mysql.php - Обёртка для работы с данными типа Phone в базе данных Mysql
            Rubric - Обёртки для работы с данными типа Rubric
                Mysql.php - Обёртка для работы с данными типа Rubric в базе данных Mysql
                Sqlite.php - Обёртка для работы с данными типа Rubric в базе данных Sqlite
            Mysql.php - Абстрактный класс для работы с данными в базе данных Mysql
            Rubric.php - Интерфейс для обёртки Rubric
            Sqlite.php - Абстрактный класс для работы с данными в базе данных Sqlite
        Api.php - Класс Api (Сожержит в себе обхекты АПИ в виде свойств. Реализовано через магический метод __get())
        Connection.php - Класс соединений с БД
        Core.php - Основной класс приложения. Синглтон.
        Helper.php - Хелпер. Хранит в себе некоторые статические методы
        Object.php - Абстрактный класс объекта
        Repository.php - Интерфейс обёртки для работы с данными

Работа с разными СУБД

Рубрики имеют древовидную структуру. Если хранить их в реляционной БД, то для получения структуры придётся делать несколько рекурсивных запросов. Было бы неплохо вынести эти данные в mongodb, но к сожалению, у меня нет возможности установить данную СУБД на сервере. Тогда, в целях разгрузки Mysql при рекурсивных запросах, я решил вынести рубрики в SQLite. На случай многопоточной работы, включим режим журналирования WAL. для ускорения выключим режим внешних ключей (тем более, их нет).

Приступим:

  1. Создадим БД

    sqlite3 /path/to/project/webapi/data/rubrics.sqlite
    sqlite> .read /path/to/project/webapi/data/structure/rubrics/sqlite.sql
    sqlite> .exit
    
  2. Если в другой СУБД есть данные, заполним их.

  3. Пропишем конфиг

    <?php
    /**
     * /path/to/project/webapi/config/config.php
     */
    return array(
    ...
        /**
         * Добавим коннекшн 
         */
        'connections' => array(
        ...
            'db2' => array(
                'type' => 'sqlile',
                'file' => '/path/to/project/webapi/data/rubrics.sqlite',
                'pragma' => array(
                    'journal_mode' => 'WAL',
                    'encoding' => 'UTF-8',
                    'foreign_keys' => '0',
                ),
            ),
        ...
        ),
         /**
          * Опишем репозиторий 
          */
        'repositories' => array(
            ...
            'rubric' => array(
                'class' => '\\Fortwogis\\Core\\Repository\\Rubric\\Sqlite',
                'connection' => 'db2',
            ),
            ...
        ),
    ...
    );

Всё. Теперь рубрики хранятся в SQLite.