diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..99fdd1a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,201 @@ +# Hyperf Development Kit + +## Feature + +The structure is based on below theories: + +* [DDD(Domain-Driven Design)](https://zh.wikipedia.org/wiki/%E9%A0%98%E5%9F%9F%E9%A9%85%E5%8B%95%E8%A8%AD%E8%A8%88) +* [TDD (Test-Driven Design)](https://zh.wikipedia.org/wiki/%E6%B5%8B%E8%AF%95%E9%A9%B1%E5%8A%A8%E5%BC%80%E5%8F%91) + +## Installation + +```sh +git clone http://124.126.16.154:8888/singularity/HyperfDevelopmentKit.git hdk \ +&& cd hdk \ +&& chown -R 1000:1000 ./scripts/ \ +&& ./scripts/docker-env.sh \ +&& composer install +``` + +## Quick Start + +All service is in *src/* . + +There are many dictionaries here to meaning each **Domain** -- you can replacing it as a *Project*. Every domain owns +their fully dictionary structures. Such as *Services* or *Constants* and so on. The main way to use these is used by * +Micro Services* and *PRC*. + +And there is a special **Domain** named *Utils*. + +***Utils*** contains fully general components. They don't need be depends on any other domain or project. You **must** +make sure them pure. + +And the test and verify way for a single package is different with classic way. + +There are two way to do it. + +1. ***(Recommand and Elegent)*** To do unit test with these testing tools below(It also named TDD). +2. *(Hack, but useful)* To require and code it in your project. For example, + 1. require hdk in LuxStudio + 2. and modify it in *vendor/*, + 3. then + 1. copy your changes to your hdk repo + 2. or commit those with git directly) + +## Testing Tools + +There are a number of testing tools available for PHP. The most popular one is [PHPUnit](https://phpunit.de/). PHPUnit +follows the classic xUnit approach. + +[Behat](http://behat.org/en/latest/) is the most popular behaviour-driven development (BDD) testing framework. + +[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is +cross-compatible with PHPUnit. + +In this guide we will be using PHPUnit as the testing framework. + +> And I'm tring to integrate [Codeception](http://codeception.com/) to hdk. + +--- + +PHP is a general-purpose server-side scripting language primarily used in web development. Originally created by Rasmus +Lerdorf in 1994, it is now by The PHP Development Team. + +PHP originally stood for "Personal Home Page", but now stands for "PHP: Hypertext Preprocessor". + +## Further Material + +- Homepage: [php.net](https://secure.php.net/) +- Documentation: [php.net/docs.php](https://secure.php.net/docs.php) +- PHP: The Right Way: [phptherightway.com](http://www.phptherightway.com/) +- Interactive PHP Tutorial: [learn-php.org](http://www.learn-php.org/) + +## Topics, Tools and Terms + +PHP packages were traditionally installed via PEAR (PHP Extension and Application Repository), but more recently the +standard package and dependency management tool is Composer. + +Composer lets us run install commands to add packages to our system, for example `composer require phpunit` would add +the unit testing framework PHPUnit to our system. + +For instructions on how to install Composer visit [getcomposer.org](https://getcomposer.org/download/). + +### Dependency Management + +Managing dependencies manually is time-consuming, fortunately Composer can automate this. + +We can list our dependencies in a `composer.json` file and run `composer install` to bring these into our project. + +An example `composer.json` file looks like this: + +```json +{ + "name": "example-project", + "require": { + "twig/twig": "^3.0" + }, + "require-dev": { + "phpunit/phpunit": "^8.4" + } +} +``` + +The "require" block tells Composer that the Twig templating package is required for production use and can install Twig +with a version of 3.x.x (ie. up to, but not including, version 4). + +The "require-dev" block tells Composer that PHPUnit is required in development, but not in production. + +Dependencies can be added to `composer.json` by + +```bash +composer require author/package-name +``` + +Development dependencies can be added by + +```bash +composer require author/package-name --dev +``` + +Dependencies can be updated to their latest maximum version by running + +```bash +composer update +``` + +Composer will also generate a `composer.lock` file on each `composer update` and the initial `composer install`. This is +not meant to be edited directly, it tells Composer to use specific versions of packages - particularly useful when hyhou +want your development dependencies to match what you will push to production. + +### Testing Tools + +There are a number of testing tools available for PHP. The most popular one is [PHPUnit](https://phpunit.de/). PHPUnit +follows the classic xUnit approach. + +[Behat](http://behat.org/en/latest/) is the most popular behaviour-driven development (BDD) testing framework. + +[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is +cross-compatible with PHPUnit. + +In this guide we will be using PHPUnit as the testing framework. + +## Directory Structure + +A typical directory structure for a PHP project consists of a `src` directory that contains all source files and +a `tests` directory that includes all tests. For web applications the publicly accessible files (eg. `index.php`) would +reside in a `public` directory which would then be your webservers document root. + +Another common convention is having a `bin` directory that may contain executable files to start your application. + +- src/ +- test/ +- public/ +- composer.json +- composer.lock + +### Naming Conventions + +Directory names are in lower case. Class and interface files should be in upper case and match the class or interface +names. +Configuration, routes, and publicly accessible files should be in lower case. + +For example the class `Example` should be contained in file `Example.php`, the publicly accessible route to the +application should be `index.php`. + +Tests match their production code file names with a `Test` suffix, e.g. tests for code in `src/Example.php` should be +written in `test/ExampleTest.php`. + +## Example Project + +The main application consists of basically two files: + +- `public/example.php` is the main executable that instantiates and runs: + - `src/Example/Greeting.php` contains the main application. + +### Running the Tests + +All tests can be run by executing + +```bash +vendor/phpunit/phpunit/phpunit +``` + +`phpunit` will automatically find all tests inside the `test` directory and run them based on the configuration in +the `phpunit.xml` file. + +#### Testing Approach + +The test for the class `Greeting` verifies that the return value of the `sayHello` method returns the string "Hello +{name}", where {name} is the value passed through to the constructor. + +### Running the Application + +PHP has an in-built server for local development. To run this change into the directory `public` and run + +```bash +php -S localhost:8000 +``` + +Then open your browser at `http://localhost:8000/example.php` + +You should see the text "Hello Ada Lovelace" being printed. diff --git a/README.md b/README.md index 29d6d01..85a51c8 100644 --- a/README.md +++ b/README.md @@ -1,206 +1,49 @@ -# Hyperf Development Kit +# HDK 最佳实践 + +通用 Hyperf 开发工具集。 A General Development Kit for Hyperf. -> 本文面向贡献者,而非使用者。 -> -> 使用者请移步 [Guide](./guide.md) +> 如果你想参与贡献,请移步 [CONTRIBUTING.md](./CONTRIBUTING.md) -## Feature +## 概述 -The structure is based on below theories: +HDK 主要包含了以下几部分内容,这也是这个库的边界: -* [DDD(Domain-Driven Design)](https://zh.wikipedia.org/wiki/%E9%A0%98%E5%9F%9F%E9%A9%85%E5%8B%95%E8%A8%AD%E8%A8%88) -* [TDD (Test-Driven Design)](https://zh.wikipedia.org/wiki/%E6%B5%8B%E8%AF%95%E9%A9%B1%E5%8A%A8%E5%BC%80%E5%8F%91) +* 开始一个新的 *Hyperf* 项目所需的脚本 +* 通用类、函数 + * 通用异常、错误码及错误捕获 -## Installation +* 项目相关 *RPC* 连接器 -```sh -git clone http://124.126.16.154:8888/singularity/HyperfDevelopmentKit.git hdk \ -&& cd hdk \ -&& chown -R 1000:1000 ./scripts/ \ -&& ./scripts/docker-env.sh \ -&& composer install -``` - -## Quick Start - -All service is in *src/* . - -There are many dictionaries here to meaning each **Domain** -- you can replacing it as a *Project*. Every domain owns -their fully dictionary structures. Such as *Services* or *Constants* and so on. The main way to use these is used by * -Micro Services* and *PRC*. - -And there is a special **Domain** named *Utils*. - -***Utils*** contains fully general components. They don't need be depends on any other domain or project. You **must** -make sure them pure. - -And the test and verify way for a single package is different with classic way. - -There are two way to do it. - -1. ***(Recommand and Elegent)*** To do unit test with these testing tools below(It also named TDD). -2. *(Hack, but useful)* To require and code it in your project. For example, - 1. require hdk in LuxStudio - 2. and modify it in *vendor/*, - 3. then - 1. copy your changes to your hdk repo - 2. or commit those with git directly) - -## Testing Tools - -There are a number of testing tools available for PHP. The most popular one is [PHPUnit](https://phpunit.de/). PHPUnit -follows the classic xUnit approach. - -[Behat](http://behat.org/en/latest/) is the most popular behaviour-driven development (BDD) testing framework. - -[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is -cross-compatible with PHPUnit. - -In this guide we will be using PHPUnit as the testing framework. - -> And I'm tring to integrate [Codeception](http://codeception.com/) to hdk. - ---- - -PHP is a general-purpose server-side scripting language primarily used in web development. Originally created by Rasmus -Lerdorf in 1994, it is now by The PHP Development Team. - -PHP originally stood for "Personal Home Page", but now stands for "PHP: Hypertext Preprocessor". - -## Further Material - -- Homepage: [php.net](https://secure.php.net/) -- Documentation: [php.net/docs.php](https://secure.php.net/docs.php) -- PHP: The Right Way: [phptherightway.com](http://www.phptherightway.com/) -- Interactive PHP Tutorial: [learn-php.org](http://www.learn-php.org/) - -## Topics, Tools and Terms - -PHP packages were traditionally installed via PEAR (PHP Extension and Application Repository), but more recently the -standard package and dependency management tool is Composer. - -Composer lets us run install commands to add packages to our system, for example `composer require phpunit` would add -the unit testing framework PHPUnit to our system. - -For instructions on how to install Composer visit [getcomposer.org](https://getcomposer.org/download/). - -### Dependency Management - -Managing dependencies manually is time-consuming, fortunately Composer can automate this. - -We can list our dependencies in a `composer.json` file and run `composer install` to bring these into our project. - -An example `composer.json` file looks like this: - -```json -{ - "name": "example-project", - "require": { - "twig/twig": "^3.0" - }, - "require-dev": { - "phpunit/phpunit": "^8.4" - } -} -``` - -The "require" block tells Composer that the Twig templating package is required for production use and can install Twig -with a version of 3.x.x (ie. up to, but not including, version 4). - -The "require-dev" block tells Composer that PHPUnit is required in development, but not in production. - -Dependencies can be added to `composer.json` by +## 安装 ```bash -composer require author/package-name +composer config secure-http false \ +&& composer config repo.lux-map composer https://satis.luxcreo.cn/ \ +&& composer require singularity/hyperf-development-kit \ +&& php bin/hyperf vendor:publish singularity/hyperf-development-kit ``` -Development dependencies can be added by +## 配置 -```bash -composer require author/package-name --dev -``` +配置,是 HDK 保证灵活性的重要一环。 -Dependencies can be updated to their latest maximum version by running +当你使用上面的命令进行安装之后,即已经发布了 HDK 的配置文件,*config/autoload/common.php*。 -```bash -composer update -``` +主要分为以下几块: -Composer will also generate a `composer.lock` file on each `composer update` and the initial `composer install`. This is -not meant to be edited directly, it tells Composer to use specific versions of packages - particularly useful when hyhou -want your development dependencies to match what you will push to production. +* 响应相关 +* 鉴权相关 +* redis 补充配置 +* 领域所需的特定配置 -### Testing Tools +## 异常处理 -There are a number of testing tools available for PHP. The most popular one is [PHPUnit](https://phpunit.de/). PHPUnit -follows the classic xUnit approach. +建议遵循以下原则: -[Behat](http://behat.org/en/latest/) is the most popular behaviour-driven development (BDD) testing framework. - -[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is -cross-compatible with PHPUnit. - -In this guide we will be using PHPUnit as the testing framework. - -## Directory Structure - -A typical directory structure for a PHP project consists of a `src` directory that contains all source files and -a `tests` directory that includes all tests. For web applications the publicly accessible files (eg. `index.php`) would -reside in a `public` directory which would then be your webservers document root. - -Another common convention is having a `bin` directory that may contain executable files to start your application. - -- src/ -- test/ -- public/ -- composer.json -- composer.lock - -### Naming Conventions - -Directory names are in lower case. Class and interface files should be in upper case and match the class or interface -names. -Configuration, routes, and publicly accessible files should be in lower case. - -For example the class `Example` should be contained in file `Example.php`, the publicly accessible route to the -application should be `index.php`. - -Tests match their production code file names with a `Test` suffix, e.g. tests for code in `src/Example.php` should be -written in `test/ExampleTest.php`. - -## Example Project - -The main application consists of basically two files: - -- `public/example.php` is the main executable that instantiates and runs: - - `src/Example/Greeting.php` contains the main application. - -### Running the Tests - -All tests can be run by executing - -```bash -vendor/phpunit/phpunit/phpunit -``` - -`phpunit` will automatically find all tests inside the `test` directory and run them based on the configuration in -the `phpunit.xml` file. - -#### Testing Approach - -The test for the class `Greeting` verifies that the return value of the `sayHello` method returns the string "Hello {name}", where {name} is the value passed through to the constructor. - -### Running the Application - -PHP has an in-built server for local development. To run this change into the directory `public` and run - -```bash -php -S localhost:8000 -``` - -Then open your browser at `http://localhost:8000/example.php` - -You should see the text "Hello Ada Lovelace" being printed. +1. 项目内的 *ErrorCode.php* **应当** 继承 `Singularity\HDK\Utils\Constants\CommonErrorCode` 类,以避免重复定义错误码 +2. 在 *config/autoload/exceptions.php* 中添加 `Singularity\HDK\Utils\Exceptions\Handler\CommonHandler::class` 行,并放置在所有捕获器的最后 + 1. 如有增加,**应当** 增加在 HDK 中(参考[CONTRIBUTING.md](./CONTRIBUTING.md)) + 2. 在项目中自行维护的情况下,**建议** 继承 `Singularity\HDK\Utils\Exceptions\Handler\CommonHandler::class` ,并在重写 `handle()` + 方法时,处理完新增异常后,调用父类的 `handle()` 方法 diff --git a/guide.md b/guide.md deleted file mode 100644 index eece61a..0000000 --- a/guide.md +++ /dev/null @@ -1,34 +0,0 @@ -# HDK 最佳实践 - -> 本文面向 HDK 的使用者,如果你想参与贡献,请移步 [README](./README.md) - -## 概述 - -HDK 主要包含了以下几部分内容,这也是这个库的边界: - -* 开始一个新的 *Hyperf* 项目所需的脚本 -* 通用类、函数 - * 通用异常、错误码及错误捕获 -* 项目相关 *RPC* 连接器 - -## 安装 - -```bash -composer config secure-http false \ -&& composer config repo.lux-map composer https://satis.luxcreo.cn/ \ -&& composer require singularity/hyperf-development-kit \ -&& php bin/hyperf vendor:publish singularity/hyperf-development-kit -``` - -## 配置 - -配置,是 HDK 保证灵活性的重要一环。 - -当你使用上面的命令进行安装之后,即已经发布了 HDK 的配置文件,*config/autoload/common.php*。 - -主要分为以下几块: - -* 响应相关 -* 鉴权相关 -* redis 补充配置 -* 领域所需的特定配置