# bw-api-user

**Repository Path**: dilam/bw-api-user

## Basic Information

- **Project Name**: bw-api-user
- **Description**: bw用户端接口项目 
- **Primary Language**: PHP
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2018-11-03
- **Last Updated**: 2022-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lumen api 项目

## 基本使用说明

### 开发环境调试

#### linux+docker(推荐)

进入devops目录，直接执行 ./dev.sh，使用的是docker-compose -f debug.yaml的配置

#### windows, linux

手动将apache或nginx目录指向 src/public/ 即可

***

## 开发

### 新增api接口

*  所有的路由入口都在 src/routes/web.php, 在v1内增加路由规则

```php
// 注意！！！所有的路由都必须在v1 group内写，不允许写在外面

// v1路由（默认）, Controller路径为app/Controllers/v1, 命名空间 App\Controllers\v1
$router->group([
    'prefix' => 'v1',
    'namespace' => 'v1',
], function ($router) {
    // POST /site/id/1
    $router->post('/site/id/{id:\d+}', 'SiteController@id');
});

```

*  在src/app/Controllers/v1目录下添加对应controller和action

```php
<?php
namespace App\Controllers\v1;

use Illuminate\Http\Request;
use App\Controllers\BaseController;
// 继承BaseController，默认有token认证
class SiteController extends BaseController
{
    // 若接口不需要token认证，自行添加
    public $allows= ['id'];

    // 第一个参数是请求request的封装，后面id则是路由表配置带过来的参数
    public function id(Request $request, $id)
    {
        return $id;
    }

}
```

### Token认证

*  请求header头 Authorization: Bearer xxxxxxx
*  若认证通过，代码内使用Auth::user()即可获取User对象(只能获取部分信息)

```php
<?php
namespace App\Controllers;

use App\Controllers\BaseController;
use Illuminate\Http\Request;
use Auth;

class AuthController extends BaseController
{
    public function check(Request $request)
    {
        // 获取 App\Auth\User, 获取部分信息id,username,role
        return Auth::user();
    }

}
```

*  若需要增加更多信息，自行在 APP\Auth\User添加（注意！该信息会编码至jwt-token，不要添加敏感信息）

```php
    /**
     * Return a key value array, containing any custom claims to be added to the JWT.
     *
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [
            'payload' => [
                "id" => $this->id,
                "username" => $this->username,
                "role" => $this->role,
            ],
        ];
    }
```

### 参数校验及获取

*  参数校验规则: https://laravel-china.org/docs/laravel/5.6/validation/1372#available-validation-rules

*  参数获取：https://laravel-china.org/docs/lumen/5.6/http-requests/1929

```php
    public function id(Request $request, $id)
    {
        // 校验失败后面代码将不会执行，能跑下去说明参数通过验证了
        $this->validate($request, [
            'name' => 'required',
            'email' => 'required|email'
        ]);
        
        // 获取单个，没有则使用默认值default
        $name = $request->input('name', 'default');
        // 获取所有参数
        $input = $request->all();
        // 只获取name,email
        $input = $request->only('name', 'email');
        // 不要email，其它都要
        $input = $request->except('email');
        return $input;
    }
```

### 响应处理

*  框架已封装统一响应结构 { "code":0, "msg":"", data:"" }
*  成功后直接返回的数据会封装到data内，错误会封装到code，msg

```php
    public function id(Request $request, $id)
    {
        if ($id != 1) {
            // 注意，该行必须在error前，否则不会执行
            Log::error("error.", ["id" => $id]);
            // 错误响应后，后面代码将不会再执行
            return error_exit(SysCode::ADMIN_FORBIDDEN, "账号被封");
        }

        return;
    }
```

### Log 打印

*  可用的log函数, 只使用debug, info, warning, error, 线上打印info以上

```php
Log::error($message);
Log::warning($message);
Log::info($message);
Log::debug($message);
```

*  log保存在 src/storage/logs/ 目录下
*  log打印结构 [时间] 级别 [文件:函数:代码行] : 文本信息 额外数组信息

```
Log::error("error.", ["id" => $id]);

[2018-09-14 11:43:11] local.ERROR ["/var/www/html/src/app/Controllers/v1/SiteController.php:id():31"] : error. {"id":"2"}
```

### 自定义配置文件及读取

1. 在src/config目录下新建，如test.php，各个环境一致的配置直接写，环境不一致的引出到env文件

```php
return [
    'normal' => 'abcdefg',
    'sp' => env('TEST_SP', 'sp');
]
```
2. 在src/bootstrap/app.php 添加 $app->configure('test');
3. 在各个.env文件加上不一样的配置，如 TEST_SP

```env
TEST_SP=sp1
```

4. 读取

```php
$n = config('test.normal'); // abcdefg
$sp = config('test.sp'); // sp1
```

### 单元测试

*  在src/tests目录下新建 xxxControllerTest.php，继承TestCase.php
*  单元测试会遍历执行test_xxx的所有函数
*  执行单条用例，在src目录下执行 ./vendor/bin/phpunit --filter 'AuthControllerTest::test_login' --testdox

```sh
./vendor/bin/phpunit --filter 'AuthControllerTest::test_login' --testdox

PHPUnit 7.2.7 by Sebastian Bergmann and contributors.

AuthController
 ✔ Login

Time: 657 ms, Memory: 12.00MB

OK (1 test, 7 assertions)
```

```php
<?php
class AuthControllerTest extends TestCase
{
    public function test_login()
    {
        $body = [
            'username' => 'admin',
            'password' => '123456',
        ];
        // Success
        $this->json('POST', '/auth/login', $body) // 构造api请求
            ->seeStatusCode(200)                  // 判断返回状态
            ->seeJsonStructure([                  // 判断返回结构
                'code',
                'data' => [
                    'user',
                    'token',
                ],
            ])
            ->seeJson([                           // 判断返回数据
                'code' => 0,
            ]);
        // Error
        $this->json('GET', '/auth/login', $body)  // 构造api请求
            ->seeStatusCode(404);                 // 判断返回状态
    }

    public function test_check()
    {
        $this->json('GET', '/auth/check')
            ->seeJsonStructure([
                'data' => [
                    'id',
                    'username',
                    'role',
                ],
            ]);
    }
}
```

### 脚本

*  在scripts目录下，所有脚本均在linux+docker环境下运行
*  single_unit_test.sh 执行单条测试用例

```sh
./single_unit_test.sh AuthControllerTest::test_login

PHPUnit 7.2.7 by Sebastian Bergmann and contributors.

AuthController
 ✔ Login

Time: 818 ms, Memory: 14.00MB

OK (1 test, 7 assertions)
```

*  unit_test.sh 执行单元测试，覆盖率检查，代码格式检查，代码质量检查等，数据生成至reports文件夹
*  update_models.sh 批量更新数据库至模型App\Models