# tp6-for-api

**Repository Path**: gavinliu0606/tp6-for-api

## Basic Information

- **Project Name**: tp6-for-api
- **Description**: 基于 ThinkPHP 6.0.x 的一个 API 示例应用
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2022-02-05
- **Last Updated**: 2024-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一个为 API 设计的示例应用

## 安装

克隆代码后，执行 `composer install` 安装依赖。

依赖安装完成后，项目根目录下新建 `.env`，并复制 `.example.env` 中的内容，按照自己的本地开发环境做调整。

## 请求 & 路由

由于专用于提供接口，所以开启了强制路由模式：

```php
// config/route.php
'url_route_must' => true,
```

示例实现中，路由文件 `route/app.php` 和 `route/admin.php` 分别定义了前台与后台的路由规则，并在 `route.php` 中定义了全局 MISS 路由。

此外，`\app\Request` 类新增了 `public function validate(array $rules, array $messages = [])`
方法以方便表单验证，而且它只返回验证规则中存在的字段，这样不仅可以过滤请求参数，还能强制你为每一个可能出现的请求参数添加验证规则。

### 示例代码

```php
<?php

declare (strict_types = 1);

namespace app\controller\index;

use app\BaseController;
use auth\facade\Auth;
use think\Request;

class AuthController extends BaseController
{
    /**
     * 用户登录
     *
     * @param  \think\Request  $request
     * @return \think\response\Json
     */
    public function login(Request $request)
    {
        $credentials = $request->validate([
            'email' => 'require|email',
            'password' => 'require',
        ]);

        if (Auth::attempt($credentials)) { /* 登录成功 */
            $user = Auth::user();
            $newAccessToken = $user->generateToken();

            return successful_response([
                'token' => $newAccessToken->plainTextToken,
            ]);
        }

        // 登录失败
        return unexpected_response(
            ERROR_CODE_BAD_CREDENTIALS,
            'Incorrect email or password.',
            401
        );
    }
    
    // ……
}
```

接口消费者的所有请求的请求头中都应该携带 `Accept: application/json`，需要认证的接口还应该携带 `Authorization: Bearer {token}` 请求头。

## 统一的 JSON 响应格式

公共函数文件 `app/common.php` 定义了两个用于向客户端返回统一 JSON 格式的函数：

```php
if (!function_exists('successful_response')) {
    /**
     * 统一返回请求成功时的数据响应
     *
     * @param  array|null  $result  预期的结果数据
     * @param  string  $message  提示信息
     * @param  int  $statusCode  HTTP 状态码，一般会收到三种状态码范围，2xx 表示请求符合预期，4xx 表示终端提供的信息导致出现错误，5xx 表示服务器出现错误，不常见
     * @return \think\response\Json
     */
    function successful_response(
        ?array $result = null,
        string $message = 'success',
        int $statusCode = 200
    ): \think\response\Json {
        return json([
            'code' => '0000',
            'msg' => $message,
            'result' => $result,
        ], $statusCode);
    }
}

if (!function_exists('unexpected_response')) {
    /**
     * 统一返回不符合预期的数据响应
     *
     * @param  int  $errCode  平台错误代码
     * @param  string  $errMsg  错误消息
     * @param  int  $statusCode  HTTP 状态码，一般会收到三种状态码范围，2xx 表示请求符合预期，4xx 表示终端提供的信息导致出现错误，5xx 表示服务器出现错误，不常见
     * @return \think\response\Json
     */
    function unexpected_response(int $errCode, string $errMsg, int $statusCode): \think\response\Json
    {
        return json([
            'code' => (string) $errCode,
            'msg' => $errMsg,
            'result' => null,
        ], $statusCode);
    }
}
```

所有错误代码全部定义在项目根目录下的 `constant/successful_response` 中。

## 扩展服务

### 用户认证

用户认证服务移植于 Laravel 的 [Authentication](https://laravel.com/docs/9.x/authentication)，代码位于 `extend/auth/` 目录下。

新增的 `config/auth.php` 配置文件用于配置认证服务。

### 哈希服务

哈希服务移植于 Laravel 的 [Hashing](https://laravel.com/docs/9.x/hashing)，代码位于 `extend/hashing/` 目录下。

配置文件 `config/app.php` 中的 `hash_algo` 用于配置哈希算法。

> 目前只支持 `bcrypt` 算法。

### 其他扩展

位于 `extend/support` 目录下的是一些辅助工具，目前提供的有：

- 字符串处理：`\support\Str::class`