控制器接口

控制器（controller）在系统或者插件下 controller 文件夹下，使用 springboot 开发，遵循 restfulapi 接口规范，开发之前请掌握相关知识

打开系统你会发现 controller 下有 adminapi ， api， core 子项文件夹，这里是系统将不同的端口放在一起统一管理，包括后期插件开发也是分成不同端口。

接口使用 restfulapi 开发，命名为：主题+ Controller ， 接口命名规范：adminapi（api）/插件或者模块名称/功能子项模块或者功能名称/功能名称/参数

例如：adminapi/member/member_account/{id} 代表 adminapi 端口，会员模块，会员账户，对应 id 的账户详情

adminapi/shop/goods/goods_category 代表 adminapi 端口，商城插件，商品模块，商品分类

控制器基本结构

基础控制器实现

@RestController
@RequestMapping("adminapi/shop/goods")
@Description("商品管理")
public class ShopGoodsController {

    @Resource
    IShopGoodsService goodsService;

    // 控制器方法...
}

核心注解说明

类级别注解：

@RestController  // 标识为REST控制器，自动返回JSON
@RequestMapping("adminapi/shop/goods")  // 定义请求路径前缀
@Description("商品管理")  // JFR描述
@SaCheckLogin  // 权限控制，需要登录

方法级别注解：

@GetMapping("")  // 处理GET请求
@PostMapping("")  // 处理POST请求  
@PutMapping("/{id}")  // 处理PUT请求
@DeleteMapping("/{id}")  // 处理DELETE请求
@Description("获取商品分页列表")

请求参数处理

路径参数

@GetMapping("/{id}")
@Description("获取商品详情")
public Result<ShopGoodsInfoVo> info(@PathVariable("id") Integer id) {
    ShopGoodsInfoVo info = goodsService.info(id);
    return Result.success(info);
}

查询参数

@GetMapping("")
@Description("获取商品分页列表")
public Result<PageResult<ShopGoodsListVo>> list(
        @Validated PageParam pageParam,  // 分页参数
        @Validated ShopGoodsSearchParam searchParam) {  // 搜索条件
    return Result.success(goodsService.page(pageParam, searchParam));
}

请求体参数

@PostMapping("")
@Description("添加商品")
public Result<Object> add(@Validated @RequestBody ShopGoodsParam addParam) {
    goodsService.add(addParam);
    return Result.success();
}

复杂参数处理

@GetMapping("/select")
@Description("获取商品选择分页列表")
public Result<ShopSelectGoodsListVo> getSelectPage(
        @Validated PageParam pageParam,
        @Validated ShopGoodsSelectSearchParam searchParam,
        @RequestParam(name = "goods_ids[]", required = false) List<Integer> goodsIds,
        @RequestParam(name = "sku_ids[]", required = false) List<Integer> skuIds) {
    searchParam.setGoodsIds(goodsIds);
    searchParam.setSkuIds(skuIds);
    return Result.success(goodsService.getSelectPage(pageParam, searchParam));
}

权限控制

类级别权限控制

@RestController
@RequestMapping("adminapi/shop/goods")
@SaCheckLogin  // 整个控制器需要登录
public class ShopGoodsController {
    // ...
}

方法级别权限控制

@PutMapping("/{id}/status")
@Description("修改商品状态")
@SaCheckPermission("shop:goods:status")  // 需要特定权限
public Result<Object> editStatus(@PathVariable("id") Integer id, @RequestBody StatusParam statusParam) {
    goodsService.editStatus(id, statusParam);
    return Result.success();
}

完整控制器示例

ShopGoodsController 完整实现

package com.niu.shop.controller.adminapi.goods;

import com.niu.core.common.domain.Result;
import com.niu.core.common.param.PageParam;
import com.niu.core.common.vo.PageResult;
import com.niu.shop.service.admin.goods.IShopGoodsService;
import com.niu.shop.service.admin.goods.param.*;
import com.niu.shop.service.admin.goods.vo.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import jakarta.annotation.Resource;

@RestController
@RequestMapping("adminapi/shop/goods")
@Description("商品管理")
public class ShopGoodsController {

    @Resource
    IShopGoodsService goodsService;

    /**
     * 商品列表
     */
    @GetMapping("")
    @Description("获取商品分页列表")
    public Result<PageResult<ShopGoodsListVo>> list(
            @Validated PageParam pageParam,
            @Validated ShopGoodsSearchParam searchParam) {
        return Result.success(goodsService.page(pageParam, searchParam));
    }

    /**
     * 商品详情
     */
    @GetMapping("/{id}")
    @Description("获取商品详情")
    public Result<ShopGoodsInfoVo> info(@PathVariable("id") Integer id) {
        ShopGoodsInfoVo info = goodsService.info(id);
        return Result.success(info);
    }

    /**
     * 添加商品
     */
    @PostMapping("")
    @Description("添加商品")
    public Result<Object> add(@Validated @RequestBody ShopGoodsParam addParam) {
        goodsService.add(addParam);
        return Result.success();
    }

    /**
     * 编辑商品
     */
    @PutMapping("/{id}")
    @Description("编辑商品")
    public Result<Object> edit(@PathVariable("id") Integer id, @Validated @RequestBody ShopGoodsParam editParam) {
        goodsService.edit(id, editParam);
        return Result.success();
    }

    /**
     * 删除商品
     */
    @DeleteMapping("/{id}")
    @Description("删除商品")
    public Result<Object> del(@PathVariable("id") Integer id) {
        goodsService.del(id);
        return Result.success();
    }

    /**
     * 商品上下架
     */
    @PutMapping("/{id}/status")
    @Description("商品上下架")
    public Result<Object> editStatus(@PathVariable("id") Integer id, @RequestBody StatusParam statusParam) {
        goodsService.editStatus(id, statusParam);
        return Result.success();
    }

    /**
     * 商品回收站列表
     */
    @GetMapping("/recyclePage")
    @Description("商品回收站列表")
    public Result<PageResult<ShopGoodsListVo>> recyclePage(
            @Validated PageParam pageParam,
            @Validated ShopGoodsSearchParam searchParam) {
        return Result.success(goodsService.recyclePage(pageParam, searchParam));
    }

    /**
     * 商品恢复
     */
    @PutMapping("/{id}/recycle")
    @Description("商品恢复")
    public Result<Object> recycle(@PathVariable("id") Integer id) {
        goodsService.recycle(id);
        return Result.success();
    }

    /**
     * 商品彻底删除
     */
    @DeleteMapping("/{id}/destroy")
    @Description("商品彻底删除")
    public Result<Object> destroy(@PathVariable("id") Integer id) {
        goodsService.destroy(id);
        return Result.success();
    }

    /**
     * 批量彻底删除
     */
    @DeleteMapping("/destroyBatch")
    @Description("批量彻底删除")
    public Result<Object> destroyBatch(@RequestBody GetGoodsIdsParam getGoodsIdsParam) {
        goodsService.destroyBatch(getGoodsIdsParam);
        return Result.success();
    }
}