api 接口开发指南

api 接口架构概述

插件的api接口主要分为两大块：

adminapi 后台接口层：用于后台管理系统调用，提供数据管理和业务操作功能。后台接口的文件存放路径为：niucloud/addon/hello_world/app/adminapi/
api 前台接口层：用于前端应用调用，提供用户交互相关功能。前台接口的文件存放路径为：niucloud/addon/hello_world/app/api/

目录结构

后台接口目录结构

niucloud/addon/hello_world/app/adminapi/
├── controller/                                 # 控制器目录
│   ├── user/                                   # 用户模块控制器
│   │   └── User.php                            # 用户控制器
├── route/                                      # 路由目录
│   └── route.php                               # 路由定义文件

前台接口目录结构

niucloud/addon/hello_world/app/api/
├── controller/                                 # 控制器目录
│   ├── user/                                   # 用户模块控制器
│   │   └── User.php                            # 用户控制器
├── route/                                      # 路由目录
│   └── route.php                               # 路由定义文件

控制器开发规范

继承基类

后台控制器必须继承 BaseAdminController

namespace addon\hello_world\app\adminapi\controller\user;

use addon\hello_world\app\service\admin\UserService;
use core\base\BaseAdminController;
/**
 * 用户管理控制器
 * Class User
 * @package addon\hello_world\app\adminapi\controller\user
 */
class User extends BaseAdminController
{
  // todo 编写业务代码
}

前台控制器必须继承 BaseApiController

namespace addon\hello_world\app\api\controller\user;

use addon\hello_world\app\service\api\UserService;
use core\base\BaseApiController;
/**
 * 用户管理控制器
 * Class User
 * @package addon\hello_world\app\api\controller\user
 */
class User extends BaseApiController
{
  // todo 编写业务代码
}

方法命名

控制器方法名应与路由名称保持一致，例如：

// 路由定义
Route::get('user/pages', 'User@pages');

// 控制器方法
public function pages() {
    // 实现代码
}

参数获取

使用 $this->request->params() 获取请求参数：

$data = $this->request->params([
    ["keyword", ""],    // 搜索关键词
    ["page", 1],       // 页码
    ["page_size", 10]  // 每页数量
]);

响应格式

使用 success() 函数返回成功响应：

return success($data);

路由定义规范

注意事项

插件开发中，路由的处理和框架本身的路由写法有些区别。实质上是一样的。

addon\hello_world\app\adminapi\route\route.php 插件中管理端路由位置，文件名必须为 route.php

addon\hello_world\app\api\route\route.php插件中前端路由位置，文件名必须为 route.php

代码中请求路由地址的访问不需要带 addon，只是在插件路由的配置文件(route.php)中才需要写addon

后端 https://www.xxx.com/adminapi/hello_world/index

前端 https://www.xxx.com/api/hello_world/index

路由分组

所有路由必须放在与插件名称相同的分组下，以避免路由冲突：

// 后台路由
Route::group('hello_world', function () {
    // 路由定义...
});

// 前台路由
Route::group('hello_world', function () {
    // 路由定义...
});

路由中间件

后台路由中间件

后台路由通常需要添加以下中间件：

->middleware([
    AdminCheckToken::class, 
    AdminCheckRole::class, 
    AdminLog::class
]);

AdminCheckToken::class：在请求接口之前，检测当前用户是否登录，token验证
AdminCheckRole::class：在请求接口之前，检测当前用户权限验证
AdminLog::class：在请求接口时，写入用户操作日志，便于跟踪操作行为

前台路由中间件

前台路由通常需要添加以下中间件：

->middleware([
    ApiCheckToken::class,
    ApiChannel::class,
    ApiLog::class
]);

->middleware(ApiCheckToken::class, true) // true 表示验证登录

ApiChannel::class：api渠道处理, 各种渠道的请求, 会在这儿将渠道的公共数据处理好
ApiCheckToken::class：在请求接口之前，检测用户是否登录，token验证
ApiLog::class：在请求接口时，写入用户操作日志，便于跟踪操作行为

定义接口路由

采用Restful API设计开发。四种请求方式：get、post、put、delete

请求方式	用途	适用操作	参数传递方式	示例
GET	用于获取资源或数据，不改变服务器状态	查询列表、获取详情、搜索等操作	通常通过URL查询字符串或URL路径参数	获取商品品牌列表、获取商品品牌详情
POST	用于创建新资源	添加数据、提交表单等操作	通常通过请求体（body）	添加商品品牌
PUT	用于更新已存在的资源	编辑数据、修改状态等操作	通常通过请求体（body）结合URL路径参数	编辑商品品牌、修改商品品牌排序号
DELETE	用于删除指定资源	删除数据等操作	通常通过URL路径参数	删除商品品牌

后端定义接口路由地址

<?php

use app\adminapi\middleware\AdminCheckRole;
use app\adminapi\middleware\AdminCheckToken;
use app\adminapi\middleware\AdminLog;
use think\facade\Route;

/**
 * 商城系统
 */
Route::group('shop', function () {

    //商品品牌分页列表
    Route::get('goods/brand', 'addon\shop\app\adminapi\controller\goods\Brand@pages');

    //商品品牌列表
    Route::get('goods/brand/list', 'addon\shop\app\adminapi\controller\goods\Brand@lists');

    //商品品牌详情
    Route::get('goods/brand/:id', 'addon\shop\app\adminapi\controller\goods\Brand@info');

    //添加商品品牌
    Route::post('goods/brand', 'addon\shop\app\adminapi\controller\goods\Brand@add');

    //编辑商品品牌
    Route::put('goods/brand/:id', 'addon\shop\app\adminapi\controller\goods\Brand@edit');

    //删除商品品牌
    Route::delete('goods/brand/:id', 'addon\shop\app\adminapi\controller\goods\Brand@del');

    // 修改商品品牌排序号
    Route::put('goods/brand/sort', 'addon\shop\app\adminapi\controller\goods\Brand@modifySort');

})->middleware([
    AdminCheckToken::class,
    AdminCheckRole::class,
    AdminLog::class
]);

前端请求接口路由

/**
 * 获取商品品牌分页列表
 * @param params
 * @returns
 */
export function getBrandPageList(params: Record<string, any>) {
    return request.get(`shop/goods/brand`, { params })
}

/**
 * 获取商品品牌列表
 * @param params
 * @returns
 */
export function getBrandList(params: Record<string, any>) {
    return request.get(`shop/goods/brand/list`, { params })
}

/**
 * 获取商品品牌详情
 * @param brand_id 商品品牌brand_id
 * @returns
 */
export function getBrandInfo(brand_id: number) {
    return request.get(`shop/goods/brand/${ brand_id }`);
}

/**
 * 添加商品品牌
 * @param params
 * @returns
 */
export function addBrand(params: Record<string, any>) {
    return request.post('shop/goods/brand', params, { showErrorMessage: true, showSuccessMessage: true })
}

/**
 * 编辑商品品牌
 * @param params
 * @returns
 */
export function editBrand(params: Record<string, any>) {
    return request.put(`shop/goods/brand/${ params.brand_id }`, params, {
        showErrorMessage: true,
        showSuccessMessage: true
    })
}

/**
 * 修改商品品牌排序号
 * @param params
 */
export function modifyBrandSort(params: Record<string, any>) {
    return request.put(`shop/goods/brand/sort`, params, { showSuccessMessage: true })
}

/**
 * 删除商品品牌
 * @param brand_id
 * @returns
 */
export function deleteBrand(brand_id: number) {
    return request.delete(`shop/goods/brand/${ brand_id }`, { showErrorMessage: true, showSuccessMessage: true })
}

接口调用成功后的结果

自定义接口端口配置

在插件开发中，可以根据业务需求定义自定义的接口端口，例如：

openapi：开放平台接口，用于第三方系统对接。