Files
main/.claude/skills/fangjia-openapi-dev/references/code-templates.md
T

4.8 KiB

OpenAPI 接口开发代码模板

Controller 模板

package com.fangjia.open.controllers;

import com.fangjia.open.model.*;
import com.fangjia.service.{业务模块}.{Service名称};
import com.fangjia.open.interceptors.Authority;
import com.fangjia.open.interceptors.Role;
import org.apache.commons.lang.StringUtils;

@Authority(role = Role.USER)
public class {Controller名称}Controller {

    private {Service名称} {service实例名};

    // Spring依赖注入(约定大于配置)
    public void set{Service名称}({Service名称} {service实例名}) {
        this.{service实例名} = {service实例名};
    }

    /**
     * {接口功能描述}
     * URL: /{controller路径}/{方法名}
     */
    @Authority(role = Role.USER)
    public Object {方法名}Action({Model名称} model) {
        RestfulModelAndView mav = new RestfulModelAndView();

        // 参数校验
        if (StringUtils.isBlank(model.get{必填字段}())) {
            mav.setModel(BasicModel.buildBadRequestModel("{字段}不能为空"));
            return mav;
        }

        // 调用Service
        {Result类型} result = {service实例名}.{service方法}(model);

        // 封装返回结果
        if (result != null) {
            // 情况1: 有专用DTO类
            mav.setModel(BasicModel.buildOKModel().setResult(result));

            // 情况2: 使用UniversalDto
            // UniversalDto dto = UniversalDto.newDto();
            // dto.append("fieldName1", result.getValue1());
            // dto.append("fieldName2", result.getValue2());
            // mav.setModel(BasicModel.buildOKModel().setResult(dto));
        } else {
            mav.setModel(BasicModel.buildBadRequestModel("未找到数据"));
        }

        return mav;
    }
}

Service 接口模板

package com.fangjia.service.{业务模块};

import com.fangjia.open.model.{Model名称};
import {Result类的包路径}.{Result类名};

/**
 * {Service功能描述}
 */
public interface {Service名称} {

    /**
     * {方法功能描述}
     * @param model 输入参数
     * @return {返回值描述}
     */
    {Result类型} {方法名}({Model名称} model);
}

Service 实现类模板

package com.fangjia.service.{业务模块};

import com.fangjia.dal.{DAO包路径}.{DAO名称};
import com.fangjia.open.model.{Model名称};
import {Result类的包路径}.{Result类名};

/**
 * {Service功能描述}实现类
 */
public class {Service名称}Impl implements {Service名称} {

    private {DAO名称} {dao实例名};

    // Spring依赖注入
    public void set{DAO名称}({DAO名称} {dao实例名}) {
        this.{dao实例名} = {dao实例名};
    }

    @Override
    public {Result类型} {方法名}({Model名称} model) {
        // 业务逻辑实现
        // 示例:从DAO查询数据
        {Result类型} result = {dao实例名}.findBy{查询条件}(
            model.get{字段1}(),
            model.get{字段2}()
        );

        // 数据处理
        if (result != null) {
            // 可以进行额外的业务处理
            // result.setXxx(...);
        }

        return result;
    }
}

Model 类模板

package com.fangjia.open.model;

/**
 * {接口名称}输入参数Model
 */
public class {Model名称} {

    private String {字段1};
    private String {字段2};
    private Integer {字段3};
    // ... 其他字段

    // Getter和Setter方法
    public String get{字段1}() {
        return {字段1};
    }

    public void set{字段1}(String {字段1}) {
        this.{字段1} = {字段1};
    }

    public String get{字段2}() {
        return {字段2};
    }

    public void set{字段2}(String {字段2}) {
        this.{字段2} = {字段2};
    }

    public Integer get{字段3}() {
        return {字段3};
    }

    public void set{字段3}(Integer {字段3}) {
        this.{字段3} = {字段3};
    }

    // ... 其他getter/setter
}

使用 UniversalDto 封装示例

// 当没有专用的Result DTO类时,使用UniversalDto
UniversalDto dto = UniversalDto.newDto();
dto.append("communityName", "陆家嘴花园");
dto.append("city", "上海市");
dto.append("district", "浦东新区");
dto.append("referencePrice", 126000);
dto.append("updateTime", "2026-01-31");

mav.setModel(BasicModel.buildOKModel().setResult(dto));

常见返回格式

// 成功返回(有数据)
mav.setModel(BasicModel.buildOKModel().setResult(result));

// 成功返回(无数据)
mav.setModel(BasicModel.buildOKModel());

// 参数错误
mav.setModel(BasicModel.buildBadRequestModel("参数错误信息"));

// 未授权
mav.setModel(BasicModel.buildUnAuthorizedModel());

// 服务器错误
mav.setModel(BasicModel.buildServerErrorModel());

// 自定义错误码
mav.setModel(BasicModel.buildModel(错误码, "错误信息"));