HDK/hdk
1
0
Fork 0
mirror of http://124.126.16.154:8888/singularity/HyperfDevelopmentKit.git synced 2026-01-15 00:35:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 重命名，guide -> readme, readme -> contributing

Browse Source 
Signed-off-by: 李东云 <dongyun.li@luxcreo.ai>
This commit is contained in:
李东云
2022-06-14 17:05:11 +08:00
parent 119bf1fd34
commit b50775f722
3 changed files with 231 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
CONTRIBUTING.md Normal file
View 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
View File

@@ -1,206 +1,49 @@
# Hyperf Development Kit # HDK 最佳实践
通用 Hyperf 开发工具集。
A General Development Kit for Hyperf. A General Development Kit for Hyperf.
> 本文面向贡献者，而非使用者。 > 如果你想参与贡献，请移步 [CONTRIBUTING.md](./CONTRIBUTING.md)
>
> 使用者请移步 [Guide](./guide.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) * 开始一个新的 *Hyperf* 项目所需的脚本
* [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 * 项目相关 *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 ```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 配置，是 HDK 保证灵活性的重要一环。
composer require author/package-name --dev
```
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. 1. 项目内的 *ErrorCode.php* **应当** 继承 `Singularity\HDK\Utils\Constants\CommonErrorCode` 类，以避免重复定义错误码
2. 在 *config/autoload/exceptions.php* 中添加 `Singularity\HDK\Utils\Exceptions\Handler\CommonHandler::class` 行，并放置在所有捕获器的最后
[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is 1. 如有增加，**应当** 增加在 HDK 中（参考[CONTRIBUTING.md](./CONTRIBUTING.md)）
cross-compatible with PHPUnit. 2. 在项目中自行维护的情况下，**建议** 继承 `Singularity\HDK\Utils\Exceptions\Handler\CommonHandler::class` ，并在重写 `handle()`
方法时，处理完新增异常后，调用父类的 `handle()` 方法
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.

34
guide.md
View File

@@ -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 补充配置
* 领域所需的特定配置