API 开发指南

本文档介绍 DSPlatform 项目中 API 开发的技术实现，包括控制器设计、服务层架构、路由配置、参数验证、响应格式等内容。

概述

DSPlatform 采用 ThinkPHP 8.0 多应用架构，为不同端提供独立的 API 服务。系统包含多个应用模块，每个应用都有完整的 MVC 结构，包括控制器、服务层、数据访问层和验证器。

技术架构

多应用架构

系统采用多应用模式，每个应用独立处理不同端的请求：

adminapi: 管理后台API，处理管理员相关操作
api: 用户端API，处理C端用户操作
merchantapi: 商户端API，处理商户管理操作
storeapi: 店铺端API，处理店铺运营操作
riderapi: 骑手端API，处理骑手相关操作
techapi: 技师端API，处理技师相关操作
bloggerapi: 博主端API，处理博主相关操作

分层架构

┌─────────────────────────────────────────────────────────────┐
│                        控制器层                              │
│  Controller (业务控制器) → BaseController (基础控制器)        │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                        服务层                                │
│  Service (业务服务) → BaseService (基础服务)                  │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                        数据访问层                            │
│  DAO (数据访问对象) → Model (数据模型)                       │
└─────────────────────────────────────────────────────────────┘

目录结构

应用目录结构

所有应用都遵循相同的目录结构：

app/{应用名}/
├── controller/           # 控制器层
│   ├── user/           # 用户相关控制器
│   ├── system/         # 系统相关控制器
│   ├── goods/          # 商品相关控制器
│   ├── order/          # 订单相关控制器
│   ├── store/          # 店铺相关控制器
│   └── validate/       # 验证器
├── service/            # 服务层
│   ├── user/          # 用户相关服务
│   ├── system/        # 系统相关服务
│   ├── goods/         # 商品相关服务
│   ├── order/         # 订单相关服务
│   └── store/         # 店铺相关服务
├── middleware/        # 中间件
│   ├── AuthorizeToken.php    # 认证中间件
│   └── AuthorizeLog.php      # 日志中间件
└── route/             # 路由配置
    ├── user.php       # 用户路由
    ├── system.php     # 系统路由
    ├── goods.php      # 商品路由
    ├── order.php      # 订单路由
    └── store.php      # 店铺路由

应用示例

adminapi 应用

app/adminapi/
├── controller/        # 管理后台控制器
├── service/          # 管理后台服务
├── middleware/       # 管理员认证中间件
└── route/           # 管理后台路由

api 应用

app/api/
├── controller/        # 用户端控制器
├── service/          # 用户端服务
├── middleware/       # 用户认证中间件
└── route/           # 用户端路由

storeapi 应用

app/storeapi/
├── controller/        # 店铺端控制器
├── service/          # 店铺端服务
├── middleware/       # 店铺认证中间件
└── route/           # 店铺端路由

控制器设计

基础控制器

所有 API 控制器都继承自 BaseController：

php

// app/BaseController.php
abstract class BaseController
{
    protected $request;
    protected $app;
    protected $batchValidate = false;
    protected $middleware = [];

    public function __construct(App $app)
    {
        $this->app = $app;
        $this->request = $this->app->request;
        $this->initialize();
    }

    protected function initialize() {}

    protected function validate(array $data, string|array $validate, array $message = [], bool $batch = false)
    {
        // 验证逻辑实现
    }
}

API 控制器基类

php

// app/deshang/base/controller/BaseApiController.php
class BaseApiController extends BaseController
{
    public function initialize() {}
}

用户控制器基类

php

// app/deshang/base/controller/BaseUserController.php
class BaseUserController extends BaseApiController
{
    public function initialize() {}
}

控制器实现示例

用户端控制器示例

php

// app/api/controller/user/User.php
namespace app\api\controller\user;

use app\deshang\base\controller\BaseUserController;
use app\api\service\user\UserService;

/**
 * @OA\Tag(name="api/user/User", description="用户基础信息接口")
 */
class User extends BaseUserController
{
    /**
     * 获取用户信息
     * @OA\Get(
     *     path="/api/user/user/info",
     *     tags={"api/user/User"},
     *     summary="获取用户信息",
     *     description="获取当前登录用户的基础信息",
     *     @OA\Response(
     *         response=200,
     *         description="操作成功",
     *         @OA\JsonContent(
     *             @OA\Property(property="code", type="integer", example=10000),
     *             @OA\Property(property="msg", type="string", example="操作成功"),
     *             @OA\Property(property="data", type="object")
     *         )
     *     )
     * )
     */
    public function getUserInfo()
    {
        $result = (new UserService())->getUserInfo();
        return ds_json_success('操作成功', $result);
    }
}

管理端控制器示例

php

// app/adminapi/controller/system/SysConfig.php
namespace app\adminapi\controller\system;

use app\deshang\base\controller\BaseAdminController;
use app\adminapi\service\system\SysConfigService;

/**
 * @OA\Tag(name="adminapi/system/SysConfig", description="系统配置管理接口")
 */
class SysConfig extends BaseAdminController
{
    /**
     * 获取系统配置列表
     * @OA\Get(
     *     path="/adminapi/system/sys-config/pages",
     *     tags={"adminapi/system/SysConfig"},
     *     summary="获取系统配置列表",
     *     description="分页获取系统配置列表",
     *     @OA\Response(
     *         response=200,
     *         description="操作成功",
     *         @OA\JsonContent(
     *             @OA\Property(property="code", type="integer", example=10000),
     *             @OA\Property(property="msg", type="string", example="操作成功"),
     *             @OA\Property(property="data", type="object")
     *         )
     *     )
     * )
     */
    public function getSysConfigPages()
    {
        $result = (new SysConfigService())->getSysConfigPages();
        return ds_json_success('操作成功', $result);
    }
}

店铺端控制器示例

php

// app/storeapi/controller/store/Store.php
namespace app\storeapi\controller\store;

use app\deshang\base\controller\BaseStoreController;
use app\storeapi\service\store\StoreService;

/**
 * @OA\Tag(name="storeapi/store/Store", description="店铺管理接口")
 */
class Store extends BaseStoreController
{
    /**
     * 获取店铺信息
     * @OA\Get(
     *     path="/storeapi/store/store/info",
     *     tags={"storeapi/store/Store"},
     *     summary="获取店铺信息",
     *     description="获取当前登录店铺的基础信息",
     *     @OA\Response(
     *         response=200,
     *         description="操作成功",
     *         @OA\JsonContent(
     *             @OA\Property(property="code", type="integer", example=10000),
     *             @OA\Property(property="msg", type="string", example="操作成功"),
     *             @OA\Property(property="data", type="object")
     *         )
     *     )
     * )
     */
    public function getStoreInfo()
    {
        $result = (new StoreService())->getStoreInfo();
        return ds_json_success('操作成功', $result);
    }
}

服务层设计

基础服务类

php

// app/deshang/base/BaseService.php
class BaseService
{
    protected $dao;
    protected $model;
    protected $request;

    public function __construct()
    {
        $this->request = request();
    }

    public function getPageParams()
    {
        $page_current = (int) input('param.page_current');
        $page_size = (int) input('param.page_size');

        return [
            'page_current' => $page_current > 0 ? $page_current : 1,
            'page_size' => $page_size > 0 ? $page_size : 10,
        ];
    }

    public function getPaginate($model)
    {
        $page_params = $this->getPageParams();
        return $model->paginate([
            'list_rows' => $page_params['page_size'],
            'page' => $page_params['page_current'],
        ])->toArray();
    }
}

API 服务基类

php

// app/deshang/base/service/BaseApiService.php
class BaseApiService extends BaseService
{
    protected $user_id;
    protected $user_is_enabled;
    protected $merchant_id;
    protected $merchant_is_enabled;
    protected $rider_id;
    protected $rider_is_enabled;
    protected $technician_id;
    protected $technician_is_enabled;
    protected $blogger_id;
    protected $blogger_is_enabled;

    public function __construct()
    {
        parent::__construct();
        $this->user_id = $this->request->user_id;
        $this->user_is_enabled = $this->request->user_is_enabled;
        $this->merchant_id = $this->request->merchant_id;
        $this->merchant_is_enabled = $this->request->merchant_is_enabled;
        $this->rider_id = $this->request->rider_id;
        $this->rider_is_enabled = $this->request->rider_is_enabled;
        $this->technician_id = $this->request->technician_id;
        $this->technician_is_enabled = $this->request->technician_is_enabled;
        $this->blogger_id = $this->request->blogger_id;
        $this->blogger_is_enabled = $this->request->blogger_is_enabled;
    }
}

用户服务基类

php

// app/deshang/base/service/BaseUserService.php
class BaseUserService extends BaseApiService
{
    public function __construct()
    {
        parent::__construct();

        // 验证是否获取到user_id
        if (!$this->user_id) {
            throw new CommonException('请先登录', 403);
        }

        if (!$this->user_is_enabled) {
            throw new CommonException('您账户已被禁用');
        }
    }
}

服务实现示例

用户端服务示例

php

// app/api/service/user/UserService.php
namespace app\api\service\user;

use app\deshang\base\service\BaseUserService;
use app\deshang\exceptions\CommonException;
use app\common\dao\user\UserDao;
use app\deshang\service\user\DeshangUserService;

class UserService extends BaseUserService
{
    public function __construct()
    {
        parent::__construct();
    }

    // 获取用户信息
    public function getUserInfo()
    {
        $user_info = (new UserDao())->getUserInfo(['id' => $this->user_id]);
        unset($user_info['password']);
        unset($user_info['pay_password']);
        return $user_info;
    }

    // 更新用户信息
    public function updateUserInfo($data)
    {
        return (new DeshangUserService())->updateUser($this->user_id, $data);
    }
}

管理端服务示例

php

// app/adminapi/service/system/SysConfigService.php
namespace app\adminapi\service\system;

use app\deshang\base\service\BaseAdminService;
use app\common\dao\system\SysConfigDao;

class SysConfigService extends BaseAdminService
{
    public function __construct()
    {
        parent::__construct();
    }

    // 获取系统配置分页列表
    public function getSysConfigPages()
    {
        $page_params = $this->getPageParams();
        $condition = [];
        
        // 搜索条件
        $keyword = input('param.keyword');
        if ($keyword) {
            $condition[] = ['config_name', 'like', '%' . $keyword . '%'];
        }

        $dao = new SysConfigDao();
        return $dao->getSysConfigPages($condition, $page_params);
    }

    // 更新系统配置
    public function updateSysConfig($id, $data)
    {
        $dao = new SysConfigDao();
        return $dao->updateSysConfig($id, $data);
    }
}

店铺端服务示例

php

// app/storeapi/service/store/StoreService.php
namespace app\storeapi\service\store;

use app\deshang\base\service\BaseStoreService;
use app\common\dao\store\StoreDao;

class StoreService extends BaseStoreService
{
    public function __construct()
    {
        parent::__construct();
    }

    // 获取店铺信息
    public function getStoreInfo()
    {
        $dao = new StoreDao();
        return $dao->getStoreInfoById($this->store_id);
    }

    // 更新店铺信息
    public function updateStoreInfo($data)
    {
        $dao = new StoreDao();
        return $dao->updateStore($this->store_id, $data);
    }
}

路由配置

路由文件结构

每个应用和模块都有独立的路由文件，便于管理和维护：

用户端路由示例

php

// app/api/route/user.php
use think\facade\Route;
use app\api\middleware\UserAuthorizeToken;
use app\api\middleware\UserAuthorizeLog;

Route::group('user', function () {
    // 用户基础信息
    Route::get('user/info', 'user.User/getUserInfo');
    Route::get('user/info-with-roles', 'user.User/getUserInfoWithRoles');
    Route::post('user/info', 'user.User/updateUserInfo');
    Route::post('user/edit-password', 'user.User/editUserPassword');

    // 用户地址
    Route::post('address/update', 'user.UserAddress/updateUserAddress');
    Route::get('address/list', 'user.UserAddress/getUserAddressList');
    Route::post('address/delete', 'user.UserAddress/deleteUserAddress');
    Route::get('address/info', 'user.UserAddress/getUserAddressInfo');
    Route::put('address/set_default/:id', 'user.UserAddress/setDefaultUserAddress');

    // 用户收藏
    Route::get('goods-favorites/pages', 'user.UserTblGoodsFavorites/getTblGoodsFavoritesPages');
    Route::post('goods-favorites/:id', 'user.UserTblGoodsFavorites/createTblGoodsFavorites');
    Route::delete('goods-favorites/:id', 'user.UserTblGoodsFavorites/deleteTblGoodsFavorites');
})->middleware([
    UserAuthorizeToken::class,
    UserAuthorizeLog::class,
]);

管理端路由示例

php

// app/adminapi/route/system.php
use think\facade\Route;
use app\adminapi\middleware\AdminAuthorizeToken;
use app\adminapi\middleware\AdminAuthorizeLog;

Route::group('system', function () {
    // 系统配置
    Route::get('sys-config/pages', 'system.SysConfig/getSysConfigPages');
    Route::get('sys-config/info/:id', 'system.SysConfig/getSysConfigInfo');
    Route::post('sys-config/create', 'system.SysConfig/createSysConfig');
    Route::post('sys-config/update', 'system.SysConfig/updateSysConfig');
    Route::delete('sys-config/delete/:id', 'system.SysConfig/deleteSysConfig');

    // 系统文章
    Route::get('sys-article/pages', 'system.SysArticle/getSysArticlePages');
    Route::get('sys-article/info/:id', 'system.SysArticle/getSysArticleInfo');
    Route::post('sys-article/create', 'system.SysArticle/createSysArticle');
    Route::post('sys-article/update', 'system.SysArticle/updateSysArticle');
    Route::delete('sys-article/delete/:id', 'system.SysArticle/deleteSysArticle');
})->middleware([
    AdminAuthorizeToken::class,
    AdminAuthorizeLog::class,
]);

店铺端路由示例

php

// app/storeapi/route/tblStore.php
use think\facade\Route;

Route::group('tbl-store', function () {
    // 店铺信息
    Route::get('info', 'tblStore.TblStoreInfo/getStoreInfo');
    Route::post('update', 'tblStore.TblStoreInfo/updateStoreInfo');

    // 店铺商品
    Route::get('goods/pages', 'tblGoods.TblGoods/getGoodsPages');
    Route::get('goods/info/:id', 'tblGoods.TblGoods/getGoodsInfo');
    Route::post('goods/create', 'tblGoods.TblGoods/createGoods');
    Route::post('goods/update', 'tblGoods.TblGoods/updateGoods');
    Route::delete('goods/delete/:id', 'tblGoods.TblGoods/deleteGoods');

    // 店铺订单
    Route::get('order/pages', 'tblOrder.TblOrder/getOrderPages');
    Route::get('order/info/:id', 'tblOrder.TblOrder/getOrderInfo');
    Route::post('order/update-status', 'tblOrder.TblOrder/updateOrderStatus');
});

注意: 店铺端路由目前没有使用认证中间件，可能通过其他方式处理身份验证。

路由命名规范

GET: 获取数据 (getUserInfo, getUserAddressList)
POST: 创建数据 (updateUserInfo, createTblGoodsFavorites)
PUT: 更新数据 (setDefaultUserAddress)
DELETE: 删除数据 (deleteTblGoodsFavorites)

参数验证

验证器基类

php

// app/deshang/base/BaseValidate.php
class BaseValidate extends Validate
{
    // 检测平台是否存在
    protected function checkPlatform($value, $rule, $data = []): bool
    {
        $condition = [['platform', '=', $value]];
        $result = (new SysPlatformDao())->getSysPlatformInfo($condition);
        return $result ? true : false;
    }

    // 检测商户是否存在
    protected function checkMerchant($value, $rule, $data = []): bool
    {
        $merchant = (new MerchantDao())->getMerchantInfoById($value);
        return $merchant ? true : false;
    }

    // 检测数组是否所有元素都是数字
    protected function isAllNumbers($value, $rule, $data = []): bool
    {
        foreach ($value as $item) {
            if (!is_numeric($item)) {
                return false;
            }
        }
        return true;
    }

    // 检测纬度值是否有效
    protected function checkLatitude($value, $rule, $data = []): bool
    {
        if (!is_numeric($value)) {
            return false;
        }
        return $value >= -90 && $value <= 90;
    }

    // 检测经度值是否有效
    protected function checkLongitude($value, $rule, $data = []): bool
    {
        if (!is_numeric($value)) {
            return false;
        }
        return $value >= -180 && $value <= 180;
    }

    // 检测手机验证码
    protected function checkMobileCode($value, $rule, $data = []): bool
    {
        return preg_match('/^\d{6}$/', $value);
    }
}

验证器实现示例

php

// app/api/controller/user/validate/UserValidate.php
namespace app\api\controller\user\validate;

use app\deshang\base\BaseValidate;

class UserValidate extends BaseValidate
{
    protected $rule = [
        'old_password' => 'require|min:1',
        'password' => 'require|min:6|max:32',
        'confirm_password' => 'require|confirm:password',
        'nickname' => 'max:32',
        'avatar' => 'max:255',
        'sex' => 'in:0,1,2',
        'birthday' => 'integer',
    ];

    protected $message = [
        'old_password.require' => '请输入原密码',
        'old_password.min' => '原密码不能为空',
        'password.require' => '请输入新密码',
        'password.min' => '新密码长度不能少于6位',
        'password.max' => '新密码长度不能超过32位',
        'confirm_password.require' => '请输入确认密码',
        'confirm_password.confirm' => '两次输入的密码不一致',
        'nickname.max' => '昵称长度不能超过32位',
        'avatar.max' => '头像URL长度不能超过255位',
        'sex.in' => '性别值无效',
        'birthday.integer' => '生日必须为整数',
    ];

    protected $scene = [
        'editPassword' => ['old_password', 'password', 'confirm_password'],
        'updateInfo' => ['nickname', 'avatar', 'sex', 'birthday'],
    ];
}

中间件

认证中间件

每个应用都有对应的认证中间件，用于验证不同角色的身份：

用户认证中间件

php

// app/api/middleware/UserAuthorizeToken.php
namespace app\api\middleware;

use app\Request;
use app\deshang\utils\JwtToken;

class UserAuthorizeToken
{
    public function handle(Request $request, \Closure $next)
    {
        $token = $request->header('access-token');
        
        if (strlen($token ?? '') > 0) {
            $token_info = (new JwtToken())->validateToken($token);

            if ($token_info == false) {
                return ds_json_error('登录状态已失效，请重新登录', [], 10001, 401);
            }

            if ($token_info['role'] != 'user') {
                return ds_json_error('身份验证失败，请重新登录', [], 10001, 403);
            }

            // 设置用户信息到请求对象
            $request->user_id = $token_info['user_id'] ?? 0;
            $request->username = $token_info['username'] ?? '';
            $request->user_is_enabled = $token_info['user_is_enabled'] ?? 0;
            $request->merchant_id = $token_info['merchant_id'] ?? 0;
            $request->merchant_is_enabled = $token_info['merchant_is_enabled'] ?? 0;
            $request->rider_id = $token_info['rider_id'] ?? 0;
            $request->rider_is_enabled = $token_info['rider_is_enabled'] ?? 0;
            $request->technician_id = $token_info['technician_id'] ?? 0;
            $request->technician_is_enabled = $token_info['technician_is_enabled'] ?? 0;
            $request->blogger_id = $token_info['blogger_id'] ?? 0;
            $request->blogger_is_enabled = $token_info['blogger_is_enabled'] ?? 0;
        }

        return $next($request);
    }
}

管理员认证中间件

php

// app/adminapi/middleware/AdminAuthorizeToken.php
namespace app\adminapi\middleware;

use app\Request;
use app\deshang\utils\JwtToken;

class AdminAuthorizeToken
{
    public function handle(Request $request, \Closure $next)
    {
        $token = $request->header('access-token');
        
        if (strlen($token ?? '') > 0) {
            $token_info = (new JwtToken())->validateToken($token);

            if ($token_info == false) {
                return ds_json_error('登录状态已失效，请重新登录', [], 10001, 401);
            }

            if ($token_info['role'] != 'admin') {
                return ds_json_error('身份验证失败，请重新登录', [], 10001, 403);
            }

            // 设置管理员信息到请求对象
            $request->admin_id = $token_info['admin_id'] ?? 0;
            $request->admin_username = $token_info['admin_username'] ?? '';
            $request->admin_is_enabled = $token_info['admin_is_enabled'] ?? 0;
        }

        return $next($request);
    }
}

管理员角色权限中间件

php

// app/adminapi/middleware/AdminAuthorizeRole.php
namespace app\adminapi\middleware;

use app\Request;
use app\deshang\exceptions\CommonException;

class AdminAuthorizeRole
{
    public function handle(Request $request, \Closure $next)
    {
        // 获取当前管理员角色信息
        $admin_id = $request->admin_id ?? 0;
        
        if (!$admin_id) {
            throw new CommonException('请先登录', 403);
        }

        // 检查管理员权限
        // 这里可以根据具体业务需求实现权限检查逻辑
        // 例如：检查管理员是否有访问特定功能的权限
        
        return $next($request);
    }
}

操作日志中间件

php

// app/api/middleware/UserAuthorizeLog.php
namespace app\api\middleware;

use app\Request;
use app\common\dao\system\SysAccessLogsDao;

class UserAuthorizeLog
{
    public function handle(Request $request, \Closure $next)
    {
        $start_time = microtime(true);
        
        $response = $next($request);
        
        $end_time = microtime(true);
        $duration = round(($end_time - $start_time) * 1000, 2); // 毫秒
        
        // 记录访问日志
        $log = [
            'user_id' => $request->user_id ?? 0,
            'username' => $request->username ?? '',
            'ip' => $request->ip(),
            'root' => $request->root(true),
            'method' => $request->method(),
            'controller' => $request->controller(),
            'action' => $request->action(),
            'url' => $request->url(true),
            'params' => json_encode($request->param()),
            'result' => json_encode($response->getData()),
            'duration' => $duration,
            'http_code' => $response->getCode(),
            'code' => $response->getData()['code'] ?? 0,
        ];
        
        (new SysAccessLogsDao())->createAccessLog($log);
        
        return $response;
    }
}

响应格式

统一响应函数

系统提供了统一的响应格式函数：

php

// app/common.php

/**
 * 成功响应
 */
function ds_json_success($message = '', $data = '', $code = 10000, $http_code = 200)
{
    $data = ['code' => $code, 'message' => $message, 'data' => $data];
    return json($data, $http_code);
}

/**
 * 错误响应
 */
function ds_json_error($message = '', $data = '', $code = 10001, $http_code = 200)
{
    $data = ['code' => $code, 'message' => $message, 'data' => $data];
    return json($data, $http_code);
}

响应格式规范

成功响应格式

json

{
    "code": 10000,
    "message": "操作成功",
    "data": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "avatar": "https://example.com/avatar.jpg"
    }
}

错误响应格式

json

{
    "code": 10001,
    "message": "参数错误",
    "data": []
}

分页响应格式

json

{
    "code": 10000,
    "message": "操作成功",
    "data": {
        "data": [
            {
                "id": 1,
                "name": "商品1"
            }
        ],
        "total": 100,
        "per_page": 10,
        "current_page": 1,
        "last_page": 10
    }
}

API 文档

Swagger 注解

系统使用 Swagger 注解生成 API 文档：

php

/**
 * @OA\Tag(name="api/user/User", description="用户基础信息接口")
 */
class User extends BaseUserController
{
    /**
     * @OA\Get(
     *     path="/api/user/user/info",
     *     tags={"api/user/User"},
     *     summary="获取用户信息",
     *     description="获取当前登录用户的基础信息",
     *     @OA\Response(
     *         response=200,
     *         description="操作成功",
     *         @OA\JsonContent(
     *             @OA\Property(property="code", type="integer", example=10000),
     *             @OA\Property(property="msg", type="string", example="操作成功"),
     *             @OA\Property(property="data", type="object")
     *         )
     *     )
     * )
     */
    public function getUserInfo()
    {
        // 方法实现
    }
}

开发规范

1. 命名规范

控制器: PascalCase (如：UserController, OrderController)
服务类: PascalCase (如：UserService, OrderService)
方法名: camelCase (如：getUserInfo, createOrder)
变量名: camelCase (如：$userInfo, $orderList)
常量名: UPPER_SNAKE_CASE (如：USER_STATUS_ACTIVE)

2. 目录规范

控制器: 放在对应应用的 controller/ 目录
服务类: 放在对应应用的 service/ 目录
验证器: 放在对应控制器的 validate/ 目录
路由文件: 放在对应应用的 route/ 目录

3. 代码规范

PSR-4: 遵循PSR-4自动加载规范
PSR-12: 遵循PSR-12代码风格规范
注释规范: 使用PHPDoc注释规范
Swagger: 使用Swagger注解生成API文档

4. 错误处理

使用 CommonException 抛出业务异常
统一使用 ds_json_error() 返回错误响应
错误码统一管理，避免重复

5. 参数验证

所有输入参数必须进行验证
使用验证器类进行参数验证
支持场景验证，不同操作使用不同验证规则

API 开发指南 ​

概述 ​

技术架构 ​

多应用架构 ​

分层架构 ​

目录结构 ​

应用目录结构 ​

应用示例 ​

adminapi 应用 ​

api 应用 ​

storeapi 应用 ​

控制器设计 ​

基础控制器 ​

API 控制器基类 ​

用户控制器基类 ​

控制器实现示例 ​

用户端控制器示例 ​

管理端控制器示例 ​

店铺端控制器示例 ​

服务层设计 ​

基础服务类 ​

API 服务基类 ​

用户服务基类 ​

服务实现示例 ​

用户端服务示例 ​

管理端服务示例 ​

店铺端服务示例 ​

路由配置 ​

路由文件结构 ​

用户端路由示例 ​

管理端路由示例 ​

店铺端路由示例 ​

路由命名规范 ​

参数验证 ​

验证器基类 ​

验证器实现示例 ​

中间件 ​

认证中间件 ​

用户认证中间件 ​

管理员认证中间件 ​

管理员角色权限中间件 ​

操作日志中间件 ​

响应格式 ​

统一响应函数 ​

响应格式规范 ​

成功响应格式 ​

错误响应格式 ​

分页响应格式 ​

API 文档 ​

Swagger 注解 ​

开发规范 ​

1. 命名规范 ​

2. 目录规范 ​

3. 代码规范 ​

4. 错误处理 ​

5. 参数验证 ​

相关文件 ​

基础文件 ​

控制器基类 ​

服务基类 ​

认证中间件 ​

API 开发指南

概述

技术架构

多应用架构

分层架构

目录结构

应用目录结构

应用示例

adminapi 应用

api 应用

storeapi 应用

控制器设计

基础控制器

API 控制器基类

用户控制器基类

控制器实现示例

用户端控制器示例

管理端控制器示例

店铺端控制器示例

服务层设计

基础服务类

API 服务基类

用户服务基类

服务实现示例

用户端服务示例

管理端服务示例

店铺端服务示例

路由配置

路由文件结构

用户端路由示例

管理端路由示例

店铺端路由示例

路由命名规范

参数验证

验证器基类

验证器实现示例

中间件

认证中间件

用户认证中间件

管理员认证中间件

管理员角色权限中间件

操作日志中间件

响应格式

统一响应函数

响应格式规范

成功响应格式

错误响应格式

分页响应格式

API 文档

Swagger 注解

开发规范

1. 命名规范

2. 目录规范

3. 代码规范

4. 错误处理

5. 参数验证

相关文件

基础文件

控制器基类

服务基类

认证中间件