4.1、手工创建接口

创建目录结构

按 web、service、dao、setup

创建 Controller、Vo、Service、ServiceImpl、Dao、Model、Mapper.xml

1、创建 Dao、Model 对象

IDemoDao


import org.apache.ibatis.annotations.Mapper;

import com.knowway.cloud.api.dao.BaseDao;
import com.knowway.smartedu.demo.admin.dao.entities.DemoModel;

@Mapper
public interface IDemoDao extends BaseDao<DemoModel>{

}

DemoModel


import org.apache.ibatis.type.Alias;

import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.knowway.cloud.api.dao.entities.BaseModel;

import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import lombok.experimental.Accessors;

@Alias("DemoModel")
@Accessors(chain = true)
@Getter
@Setter
@SuppressWarnings("serial")
@ToString
@EqualsAndHashCode(callSuper = true)
@TableName("DEMO_XXB")
public class DemoModel extends BaseModel {

    /**
    * 表ID
    */
    @TableId("ID")
    private String id;
    /**
     * 名称
     */
     @TableId("NAME")
    private String name;

}

2、创建 Service、ServiceImpl 对象

Service

import com.knowway.cloud.api.service.BaseService;
import com.knowway.smartedu.demo.admin.dao.entities.DemoModel;

public interface IDemoService extends BaseService<DemoModel>{


}

ServiceImpl


import org.springframework.stereotype.Service;

import com.knowway.cloud.api.service.BaseServiceImpl;
import com.knowway.smartedu.demo.admin.dao.IDemoDao;
import com.knowway.smartedu.demo.admin.dao.entities.DemoModel;
import com.knowway.smartedu.demo.admin.service.IDemoService;

@Service
public class DemoServiceImpl extends BaseServiceImpl<DemoModel, IDemoDao> implements IDemoService{



}

3、创建 Vo 对象

考虑接口的增、删、改、查，同一组Vo，应该具备新增接口Vo、修改接口Vo、查询接口Vo、分页查询接口Vo 四个

新增接口Vo：DemoNewVo

import javax.validation.constraints.NotBlank;

import org.hibernate.validator.constraints.SafeHtml;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import lombok.experimental.Accessors;

@ApiModel(value = "DemoNewVo", description = "新增xx参数Vo")
@Accessors(chain = true)
@Getter
@Setter
@ToString
public class DemoNewVo {

    @ApiModelProperty(name = "name", required = true, dataType = "String", value = "xx名称")
    @NotBlank(message = "名称必填")
    @SafeHtml(whitelistType = SafeHtml.WhiteListType.NONE)
    private String name;

}

分页查询接口Vo：DemoPaginationVo

import javax.validation.constraints.NotBlank;

import org.hibernate.validator.constraints.SafeHtml;

import com.knowway.cloud.api.vo.AbstractPaginationVo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import lombok.experimental.Accessors;

@ApiModel(value = "DemoPaginationVo", description = "xxx分页查询参数Vo")
@Accessors(chain = true)
@Getter
@Setter
@ToString
public class DemoPaginationVo extends AbstractPaginationVo {

    @ApiModelProperty(value = "xx名称", required = true)
    @NotBlank(message = "名称必填")
    @SafeHtml(whitelistType = SafeHtml.WhiteListType.NONE)
    private String name;

}

修改接口Vo：DemoRenewVo

import javax.validation.constraints.NotBlank;

import org.hibernate.validator.constraints.SafeHtml;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import lombok.experimental.Accessors;

@ApiModel(value = "DemoRenewVo", description = "xxx更新参数Vo")
@Accessors(chain = true)
@Getter
@Setter
@ToString
public class DemoRenewVo {

    @ApiModelProperty(name = "id", required = true, dataType = "String", value = "xxID")
    @NotBlank(message = "ID必填")
    private String id;

    @ApiModelProperty(name = "name", required = true, dataType = "String", value = "xx名称")
    @NotBlank(message = "名称必填")
    @SafeHtml(whitelistType = SafeHtml.WhiteListType.NONE)
    private String name;

}

查询接口Vo：DemoVo

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import lombok.experimental.Accessors;

@ApiModel(value = "DemoVo", description = "xxx数据对象Vo")
@Accessors(chain = true)
@Getter
@Setter
@ToString
public class DemoVo {

    @ApiModelProperty(value = "xxID", required = true)
    private String id;
    @ApiModelProperty(value = "xx名称", required = true)
    private String name;

}

4、创建 Controller 对象

a、创建 HomepageController 用于 swagger 文档跳转：

import javax.servlet.http.HttpServletRequest;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import springfox.documentation.annotations.ApiIgnore;

/**
 * 系统默认的重定向地址
 */
@Controller
public class HomepageController {

    @ApiIgnore
    @RequestMapping("/")
    public String index(HttpServletRequest request) {
        return "redirect:/doc.html";
    }

}

b、创建 DemoController

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.knowway.cloud.api.webmvc.BaseApiController;

@RestController
@RequestMapping("/demo/")
public class DemoController extends BaseApiController{


}

5、创建 Mapper.xml

在 src/main/resources 目录下创建与工程结构相同的目录
~~why? ：过往经验中开发人员常出现打包时候Mapper.xml丢失情况，这里从源头解决问题 ~~~

并创建结构下图：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="com.knowway.smartedu.demo.admin.dao.IDemoDao" >

    <resultMap id="DemoModelMap" type="DemoModel">
        <result property="id" column="ID" />
        <result property="name" column="NAME" />
    </resultMap>

    <insert id="insert" parameterType="DemoModel">
        insert into DEMO_XXB(NAME) values(#{name}) 
    </insert>

    <delete id="delete"  parameterType="DemoModel">
        delete from DEMO_XXB t where t.id = #{id}
    </delete>

    <delete id="batchDelete" parameterType="java.util.List">
        delete from DEMO_XXB where id in
        <foreach collection="list" item="ids"  open="(" separator="," close=")">
           #{ids}
        </foreach>
    </delete>

    <update id="update" parameterType="DemoModel">
        update DEMO_XXB 
        <set>
            <if test="name != null and name != ''">name = #{name},</if>
        </set>
        where id = #{id}
    </update>

    <select id="getPagedList" resultMap="DemoModelMap" parameterType="DemoModel">
        select ID,NAME from DEMO_XXB t
        <where>
            <if test="name != null and name != ''">t.name like '%'||#{name} ||'%'</if>
        </where>
    </select>

    <select id="getModel" resultMap="DemoModelMap" parameterType="java.lang.String">
        select ID,NAME from DEMO_XXB  t WHERE t.ID = #{id}
    </select>


</mapper>

6、创建接口，这里有新增接口、修改接口、查询接口、分页查询接口

import java.util.ArrayList;
import java.util.List;

import javax.validation.Valid;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.google.common.collect.Lists;
import com.knowway.cloud.api.ApiRestResponse;
import com.knowway.cloud.api.annotation.BusinessLog;
import com.knowway.cloud.api.annotation.BusinessType;
import com.knowway.cloud.api.utils.StringUtils;
import com.knowway.cloud.api.webmvc.BaseApiController;
import com.knowway.cloud.api.webmvc.Result;
import com.knowway.smartedu.stuworker.admin.dao.entities.DemoModel;
import com.knowway.smartedu.stuworker.admin.service.IDemoService;
import com.knowway.smartedu.stuworker.admin.setup.Constants;
import com.knowway.smartedu.stuworker.admin.web.vo.DemoNewVo;
import com.knowway.smartedu.stuworker.admin.web.vo.DemoPaginationVo;
import com.knowway.smartedu.stuworker.admin.web.vo.DemoRenewVo;
import com.knowway.smartedu.stuworker.admin.web.vo.DemoVo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(tags = {"Demo接口 : 业务实现"})
@RestController
@RequestMapping("/demo/")
@Validated
public class DemoController extends BaseApiController{

    @Autowired
    private IDemoService demoService;

    @ApiOperation(value = "获取xxx列表", notes = "分页查询xxx信息")
    @ApiImplicitParams({ 
        @ApiImplicitParam(paramType = "body", name = "paginationVo", value = "分页筛选条件", dataType = "DemoPaginationVo")
    })
    @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_LIST, opt = BusinessType.SELECT)
    @PostMapping(value = "list")
    @PreAuthorize("authenticated and (hasAuthority('demo:list') or hasAuthority('*')) ")
    @ResponseBody
    public Result<DemoVo> list(@Valid @RequestBody DemoPaginationVo paginationVo) throws Exception {
        Page<DemoModel> pageResult = getDemoService().getPagedList(null);
        List<DemoVo> retList = new ArrayList<DemoVo>();
        for (DemoModel model : pageResult.getRecords()) {
            retList.add(getBeanMapper().map(model, DemoVo.class));
        }
        return new Result<DemoVo>(pageResult, retList);
    }

    /**
     * 增加逻辑实现
     */
    @ApiOperation(value = "创建xxx信息", notes = "根据DemoVo创建xxx")
    @ApiImplicitParams({ 
        @ApiImplicitParam(paramType = "body", name = "demoVo", value = "新增功能参数", required = true, dataType = "DemoNewVo")
    })
    @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_NEW, opt = BusinessType.INSERT)
    @PostMapping("new")
    @PreAuthorize("authenticated and (hasAuthority('demo:new') or hasAuthority('*')) ")
    @ResponseBody
    public ApiRestResponse<String> newDemo(@Valid @RequestBody DemoNewVo demoVo) {
        DemoModel model = getBeanMapper().map(demoVo, DemoModel.class);
        int count = getDemoService().getCount(model);
        if(count > 0) {
            return fail("demo.new.exists");
        }
        int result = getDemoService().insert(model);
        if(result == 1) {
            return success("demo.new.success", result);
        }
        return fail("demo.new.fail", result);
    }

    /**
     * 修改逻辑实现
     */
    @ApiOperation(value = "修改xxx信息", notes = "修改xxx")
    @ApiImplicitParams({ 
        @ApiImplicitParam(paramType = "body", name = "demoVo", value = "用户信息", required = true, dataType = "DemoRenewVo")
    })
    @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_RENEW, opt = BusinessType.UPDATE)
    @PostMapping("renew")
    @PreAuthorize("authenticated and (hasAuthority('demo:renew') or hasAuthority('*')) ")
    @ResponseBody
    public ApiRestResponse<String> renew(@Valid @RequestBody DemoRenewVo demoVo) throws Exception {
        DemoModel model = getBeanMapper().map(demoVo, DemoModel.class);
        int result = getDemoService().update(model);
        if(result > 0) {
            return success("demo.renew.success", result);
        }
        return fail("demo.renew.fail", result);
    }

    /**
     * 删除逻辑实现
     */
    @ApiOperation(value = "删除xxx信息", notes = "根据ID删除xxx")
    @ApiImplicitParams({ 
        @ApiImplicitParam(name = "ids", value = "ID集合，多个使用,拼接", required = true, dataType = "String")
    })
    @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_DETAIL, opt = BusinessType.DELETE)
    @GetMapping("delete")
    @PreAuthorize("authenticated and (hasAuthority('demo:delete') or hasAuthority('*')) ")
    @ResponseBody
    public ApiRestResponse<String> delete(@RequestParam(value = "ids") String ids) throws Exception {
        List<String> idList = Lists.newArrayList(StringUtils.tokenizeToStringArray(ids));
        int total = getDemoService().batchDelete(idList);
        if(total > 0) {
            return success("demo.delete.success", total); 
        }
        return fail("demo.delete.fail", total);
    }

    @ApiOperation(value = "xx信息详情", notes = "根据ID查询xx信息")
    @ApiImplicitParams({ 
        @ApiImplicitParam( paramType = "query", name = "id", required = true, value = "ID", dataType = "String")
    })
    @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_DETAIL, opt = BusinessType.SELECT)
    @GetMapping("detail")
    @PreAuthorize("authenticated and (hasAuthority('demo:detail') or hasAuthority('*')) ")
    @ResponseBody
    public ApiRestResponse<DemoVo> detail(@PathVariable String id) throws Exception {
        DemoModel model = getDemoService().getModel(id);
        if(model == null) {
            return ApiRestResponse.empty(getMessage("demo.get.not-found"));
        }
        return ApiRestResponse.success(getBeanMapper().map(model, DemoVo.class));
    }

    public IDemoService getDemoService() {
        return demoService;
    }

}

特别注意：

Controller 需要指定 @Api(tags = {"Demo接口 : 业务实现"}) 注解，用于文档生成
方法需要指定 @ApiOperation(value = "获取xxx列表", notes = "分页查询xxx信息") 注解，用于告诉Swagger 接口名称及描述
方法需要指定 @ApiImplicitParams({@ApiImplicitParam(paramType = "body", name = "paginationVo", value = "分页筛选条件", dataType = "DemoPaginationVo")}) 注解，用于告诉Swagger 需要的参数信息
方法需要指定 @BusinessLog(module = Constants.DEMO, business = Constants.Biz.DEMO_LIST, opt = BusinessType.SELECT) 注解，这里各个参数需要根据实际情况调整，描述信息需要定义在变量对象中
方法需要指定 @PreAuthorize("authenticated and (hasAuthority('demo:list') or hasAuthority('*')) ") 注解，这个注解是 Spring Security 注解，用法和Shiro的注解相似，这里做了登录判断 + 操作权限判断；如果某方法只需要登录就可以调用，可以设置为 @PreAuthorize("authenticated")
分页查询方法返回 Result<DemoVo> 包装对象
除分页查询方法，其他所有方法返回结果必须使用 ApiRestResponse 对象进行包装，以便统一前端返回结果，如： ApiRestResponse<DemoVo>

作者：Jeebiz 创建时间：2019-07-14 00:04
更新时间：2023-12-20 16:58