OSCHINA-MIRROR/jswei-Thinkphp_restful

ThinkPHP 5.1

ThinkPHP 5.1 внес дальнейшие улучшения в базовую архитектуру, уменьшая зависимости. Основные функции включают:

использование контейнеров для унифицированного управления объектами;
поддержку Facade;
аннотированную маршрутизацию;
маршрутизацию с поддержкой междоменных запросов;
независимую конфигурацию и маршрутизацию каталогов;
отмену системных констант;
улучшенные вспомогательные функции;
механизм псевдонима библиотеки классов;
добавление условных запросов;
улучшение механизма запросов;
двухуровневую конфигурацию;
усовершенствованную инъекцию зависимостей;
промежуточное ПО (V5.1.6+).

Для работы ThinkPHP 5 требуется PHP 5.6 или выше.

Структура каталога

Исходная структура каталога выглядит следующим образом:

www  WEB部署目录（或者子目录）
├─application           应用目录
│  ├─common             公共模块目录（可以更改）
│  ├─module_name        模块目录
│    ├─common.php      模块函数文件
│    ├─controller      控制器目录
│    ├─model           模型目录
│    ├─view            视图目录
│    └─ ...            更多类库目录
│
│  ├─command.php        命令行定义文件
│  ├─common.php         公共函数文件
│  └─tags.php           应用行为扩展定义文件
│
├─config                应用配置目录
│  ├─module_name        模块配置目录
│    ├─database.php    数据库配置
│    ├─cache           缓存配置
│    └─ ...
│
│  ├─app.php            应用配置
│  ├─cache.php          缓存配置
│  ├─cookie.php         Cookie配置
│  ├─database.php       数据库配置
│  ├─log.php            日志配置
│  ├─session.php        Session配置
│  ├─template.php       模板引擎配置
│  └─trace.php          Trace配置
│
├─route                 路由定义目录
│  ├─route.php          路由定义
│  └─...                更多
│
├─public                WEB目录（对外访问目录）
│  ├─index.php          入口文件
│  ├─router.php         快速测试文件
│  └─.htaccess          用于apache的重写
│
├─thinkphp              框架系统目录
│  ├─lang               语言文件目录
│  ├─library            框架类库目录
│    ├─think           Think类库包目录
│    └─traits          系统Trait目录
│
│  ├─tpl                系统模板目录
│  ├─base.php           基础定义文件
│  ├─console.php        控制台入口文件
│  ├─convention.php     框架惯例配置文件
│  ├─helper.php         助手函数文件
│  ├─phpunit.xml        phpunit配置文件
│  └─start.php          框架入口文件
│
├─extend                扩展类库目录
├─runtime               应用的运行时目录（可写，可定制）
├─vendor                第三方类库目录（Composer依赖库）
├─build.php             自动生成定义文件（参考）
├─composer.json         composer 定义文件
├─LICENSE.txt           授权说明文件
├─README.md             README 文件
├─think                 命令行入口文件

router.php используется для поддержки php self-contained webserver и может использоваться для быстрого тестирования. После перехода в каталог public запустите команду: php -S localhost:8888 router.php. Вышеупомянутая структура каталогов и имена являются изменяемыми, что зависит от вашего файла входа и параметров конфигурации.

Руководство по обновлению

Необходимо изменить пространство имён следующих системных библиотек:

think\App => think\facade\App (или App);
think\Cache => think\facade\Cache (или Cache);
think\Config => think\facade\Config (или Config);
think\Cookie => think\facade\Cookie (или Cookie);
think\Debug => think\facade\Debug (или Debug);
think\Hook => think\facade\Hook (или Hook);
think\Lang => think\facade\Lang (или Lang);
think\Log => think\facade\Log (или Log);
think\Request => think\facade\Request (или Request);
think\Response => think\facade\Reponse (или Reponse);
think\Route => think\facade\Route (или Route);
think\Session => think\facade\Session (или Session);
think\Url => think\facade\Url (или Url).

Существующий файл конфигурации config.php разделяется на app.php cache.php и другие независимые файлы конфигурации, помещаемые в каталог config. Существующее определение маршрута route.php перемещается в каталог route.

Правила именования

ThinkPHP5 следует PSR-2 и PSR-4 стандартам автоматического импорта и также учитывает следующие стандарты:

Каталоги и файлы

каталоги не имеют строгих стандартов, поддерживаются как верблюжий регистр, так и нижний регистр с подчёркиванием;
библиотеки классов, файлы функций всегда заканчиваются на .php;
файлы классов соответствуют пространству имён и пути к каталогу, в котором находится файл класса;
имена классов и файлов классов совпадают, все классы используют верблюжий регистр (первая буква заглавная);

Функции и классы, атрибуты именования

классы именуются с использованием верблюжьего регистра и первой заглавной буквы, например, User, UserType, обычно не требуется добавлять суффиксы, например, класс UserController должен быть назван просто User;
функции именуются с использованием нижнего регистра и подчёркивания (_), например, get_client_ip;
методы именуются с использованием верблюжьего регистра и первой строчной буквы, например, getUserName;
атрибуты именуются с использованием верблюжьего регистра и первой строчной буквы, например, tableName, instance;
начинающиеся с двойного подчёркивания («__») функции или методы считаются магическими методами, такими как __call и __autoload;

Константы и конфигурация

константы именуются заглавными буквами и подчёркиванием, например, APP_PATH и THINK_PATH;
параметры конфигурации именуются строчными буквами и подчёркиванием, например, url_route_on и url_convert;

Таблицы данных и поля

таблицы данных и поля именуются нижним регистром и подчёркиванием, и обратите внимание, что имена полей не должны начинаться с подчёркивания, например, таблица think_user и поле user_name, не рекомендуется использовать верблюжий регистр и китайские символы в качестве имён таблиц данных и полей.

Участие в разработке

Пожалуйста, обратитесь к ThinkPHP5 Core Framework Package.

Информация об авторских правах

ThinkPHP лицензирован под Apache 2.0 и доступен бесплатно для использования.

Этот проект включает сторонние исходные коды и двоичные файлы, авторские права которых указаны отдельно.

Торговая марка ThinkPHP® и авторские права принадлежат Shanghai Topthink Information Technology Co., Ltd.

Для получения дополнительной информации см. LICENSE.txt.

Об изменениях в dawn-api

Здесь снова внесены изменения в dawn-api, ниже приведены некоторые из изменённых мест:

Оптимизировано и использовано автоматическое включение расширенных функций, освобождая необходимость вручную писать в extraActionList каждый раз.
Вики-документация может быть отмечена с помощью аннотаций, освобождая от необходимости писать параметры в getRules(), чтобы отобразить их. Конечно, это всего лишь оптимизация, вы всё ещё можете написать там, здесь я в основном использую аннотации. Ниже приводится пример использования аннотаций на примере login: Пользовательский логин

/**
 * @title 用户登录
 * @method login 
 * @param string $phone 账号 true
 * @param string $password 密码 true md5
 * @route('v1/user/login')
 * @return Object User 用户信息
 */

@title — название интерфейса.
@method — метод, реализованный в аннотации. В данном случае это метод login.
@param — список параметров через пробел. Формат: [тип данных, формальный параметр, имя параметра, обязательный или нет, комментарий, диапазон значений].
@route — аннотация маршрута. Отображается после метода.
@return — тип возвращаемых данных через пробел. Формат: [тип данных, имя параметра, комментарий].

Эффект после завершения:

Результат применения аннотаций к методу login:

![注解显示效果](http://api.jswei.cn/images/login.png)

Использование аннотаций ThinkPHP 5.1.X делает маршрутизацию более гибкой и разнообразной. Приведённый выше пример использует аннотацию маршрутизации. Для получения дополнительной информации о маршрутизации аннотаций см. ThinkPHP 5_1.

О Dawn-API

Для удобства использования здесь представлен модифицированный Dawn-API, который также был отправлен в проект.
Первоначально загруженный API не был адаптирован и поэтому не поддерживал ThinkPHP 5.1.X.
Дополнительную информацию о конфигурации и вики можно найти в документации по Dawn-API.
Модификации не являются полностью зрелыми, поэтому при возникновении проблем рекомендуется их обсудить.

Добавление инструмента командной строки

Для удобства использования в этом разделе добавлен инструмент командной строки, который позволяет быстро создавать контроллеры API. Ниже приводится краткое описание.

После перехода в каталог проекта введите php ./think, чтобы просмотреть доступные команды. Если вы видите команду api, это означает, что вы можете использовать предоставленный инструмент командной строки. Результат будет выглядеть следующим образом:

![команда line](http://api.jswei.cn/images/line01.png)

Используйте команду php ./think api -s first -c news для создания контроллера с пространством имён first и именем news. После выполнения команды появится сообщение «Success», что означает успешное создание. Результат будет выглядеть так:

![wiki документ](http://api.jswei.cn/images/line02.png)

После успешного выполнения команды вы увидите, что в каталоге проекта появился файл application\first\controller с именем News.php. Этот файл содержит некоторые методы, которые были созданы для вас.
Одновременно с созданием контроллера в файле конфигурации api_doc.php была создана соответствующая конфигурация документа. Результат будет выглядеть следующим образом:

![wiki документ](http://api.jswei.cn/images/line03.png)

Теперь, когда вы открываете вики, вы можете увидеть базовую документацию по API. Результат будет выглядеть так:

![wiki документ](http://api.jswei.cn/images/line04.png)

На этом этапе вы можете нажать на адрес API, чтобы проверить, успешно ли он работает (здесь используется BaseAuth, и браузер предложит окно входа в систему). Результат будет выглядеть следующим образом:

![wiki документ](http://api.jswei.cn/images/line05.png)

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

Описание команд API

Ниже представлено подробное описание предоставленных параметров для вашего удобства.

Сначала вы можете использовать php ./think api -h для просмотра справки. Вы получите следующий результат:

![wiki документ](http://api.jswei.cn/images/line06.png)

-s or --namespace — пространство имён создаваемого контроллера.
-c or --controller — имя создаваемого контроллера.
-i or --id — идентификатор конфигурации документа, по умолчанию увеличивается на единицу.
-p or --parent — родительский идентификатор документа в качестве дочернего узла, по умолчанию равен 0 (верхний уровень).

Вот несколько примеров:

php ./think api -s first -c sub -p 5 #для создания дочернего документа с идентификатором 5, идентификатор автоматически увеличивается
php ./think api -s first -c sub1 -i 8 #создать документ с идентификатором 8, родительским уровнем является верхний уровень
php ./think api -s first -c sub2 -i 9 -p 5 #создать дочерний документ с идентификатором 9 для родительского документа с идентификатором 5

После успешного выполнения:

![wiki документ02](http://api.jswei.cn/images/line07.png)

![wiki документ03](http://api.jswei.cn/images/line08.png)

![wiki документ04](http://api.jswei.cn/images/line09.png)

![wiki документ04](http://api.jswei.cn/images/line10.png)

Онлайн-пример

Онлайн-пример WIKI

Документация по интерфейсу Postman