mirror of
http://124.126.16.154:8888/singularity/HyperfDevelopmentKit.git
synced 2026-01-15 00:35:08 +08:00
docs: 重命名，guide -> readme, readme -> contributing
Signed-off-by: 李东云 <dongyun.li@luxcreo.ai>
This commit is contained in:
李东云
201
CONTRIBUTING.md
Normal file
201
CONTRIBUTING.md
Normal file
@@ -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.
|
||||
217
README.md
217
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()` 方法
|
||||
|
||||
34
guide.md
34
guide.md
@@ -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 补充配置
|
||||
* 领域所需的特定配置
|
||||
Reference in New Issue
Block a user