接口开发

概述

接口主要用于对柔性设计平台之后的程序做数据对接 如 移动端 PDA等

接口必须写个项目目录Web 包下 如 ent层 web包 下 DataBaseController

接口注解

接口 注解使用@Controller 或者@ResetController 写在类上方

支持 RequestMapping、GetMapping、PostMapping、ResponseBody等常见注解

@Controller

@Controller是 Spring MVC 中的一个核心注解，用于标记一个类作为 Web 请求控制器。它属于 Spring 的 @Component 派生产品，通常结合@RequestMapping、@GetMapping、@PostMapping 注解定义请求映射。

@Controller 标记 整个类 作为控制器，由 Spring IoC 容器自动管理 需配合 @RequestMapping 等注解，定义具体的请求方法映射 默认是 singleton（单例），可通过 @Scope修改（如 prototype）

示例代码

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

@Controller  // 声明为控制器
@RequestMapping("/user")  // 类级别路径映射
public class UserController {

    // GET请求：/user/profile?id=123
    @GetMapping("/profile")
    @ResponseBody  // 直接返回数据（非视图）
    public String getUserProfile(@RequestParam int id) {
        return "User ID: " + id;
    }
    //必要场景下参数名称和类型对应 
    //如果特殊场景 参数名称可以与Url上参数名称不对应 需写@RequestParam(value = "url参数名称")

    @GetMapping("/profile")
    @ResponseBody
    // URL: /profile?uid=123   → 方法参数接收为 `userId`
    public String getProfile(@RequestParam(value = "uid") String userId) {
        "UserID: " + userId; // 输出: UserID: 123
    }

    @GetMapping("/user/{uid}")
    @ResponseBody
    // URL: /user/456   → 方法参数接收为 `userId`
    public String getUser(@PathVariable("uid") String userId) {
        return "UserID: " + userId; // 输出: UserID: 456
    }

    // POST请求：/user/update
    @PostMapping("/update")
    public String updateUser(@RequestBody String body) {
        // 业务逻辑处理
        return "redirect:/success";  // 返回视图名
    }
}

@RestController

@RestController 是 Spring MVC 中用于构建 RESTful API 的核心注解，它集合了 @Controller和 @ResponseBody 的功能，专门用于返回数据（如 JSON/XML）

示例代码

import org.springframework.web.bind.annotation.*;

@RestController  // 关键注解
@RequestMapping("/api")
public class UserController {

    // GET 请求：/api/user/123
    @GetMapping("/user/{id}")
    public String getUser(@PathVariable Long id) {
        return "";
    }

    // POST 请求：/api/user
    @PostMapping("/user")
    public String createUser(@RequestBody String body) {
        // 保存用户逻辑...
        return "";
    }
}

[!NOTE]

@Controller 与@RestController 只需存在一个

一般场景下推荐使用 @RestController

@RequestMapping

一个注解，用于将 HTTP 请求映射到处理方法上。它可以用于类或方法上，以定义如何处理特定的请求。 提供了一种灵活的方式来处理 RESTful 风格的请求，并支持多种 HTTP 方法（如 GET、POST、PUT、DELETE 等）

    @RequestMapping("/users")
    public String getUsers() {
        return "userList";
    }

    @RequestMapping("/users",method = RequestMethod.GET)
    public String getUsers() {
        return "userList";
    }

    @RequestMapping("/users/{userId}")  // URL: /users/123
    public String getUser(@PathVariable String userId) {
        return "User ID: " + userId;
    }

@GetMapping

@RequestMapping(method = RequestMethod.GET)的简化形式，专门用于处理 GET 请求。它通常用于获取资源

    @GetMapping("/users")
    public String getUsers() {
        // 返回用户列表
    }

@PostMapping

@RequestMapping(method = RequestMethod.POST)的简化形式，专门用于处理 POST 请求。它通常用于创建新资源

    @PostMapping("/users")
    public User createUser(@RequestBody String body) {
        // 创建新用户
    }

[!NOTE]

@RequestMapping @PostMapping @GetMapping 只需存在一个 根据接口类型的不同 决定使用其中一个

@RequestBody

注解用于将请求体中的数据绑定到处理方法的参数上。它通常用于处理 POST 或 PUT 请求，以获取客户端发送的 JSON 或 XML 数据

    @PostMapping("/users")
    public User createUser(@RequestBody String body) {
        //参数将从请求体中解析而来
       JSONObject parseObject = JSON.parseObject("body");
    }

[!NOTE]

在POST 请求中接收 JSON/XML 数据（REST API 常见）或者是 接收纯文本 二进制数据时 需要@RequestBody

在接收表单数据时 不需要 @RequestBody 用@RequestParam去接收对应参数

@ResponseBody

注解用于指示控制器方法的返回值应该直接写入 HTTP 响应体，而不是被视为视图名。这在 RESTful API 中非常常见，用于返回 JSON、XML 等格式的数据

    @GetMapping("/users/{id}")
    @ResponseBody
    public User getUser(@PathVariable String id) {
        // 返回用户对象作为 JSON 响应
    }

[!NOTE]

如果使用 @Controller 在请求中 希望方法直接返回数据（如 JSON、纯文本），而非视图名称 则必须添加

如果使用 @RestController 则可省略

@PathVariable

注解用于将 URI 模板中的变量绑定到处理方法的参数上。它允许在 URL 中定义动态路径参数

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable String id) {
        // 根据路径变量 id 获取用户
    }

@Authorize

柔性开发平台 在web接口开发过程中 提供了@Authorize 用于处理非登录场景

匿名登录注解 @Authorize 可选配 匿名登录 不做处理 和 正常登录 可以不写 默认要求登录才能访问

@Authorize(policy = AuthorizePolicy.None) //不做处理 一般用于接口登录 接口能进但是涉及到需要登录的 场景则会报错
@Authorize(policy = AuthorizePolicy.Anonymous) //匿名登录 该接口内所有逻辑校验登录用户信息匿名访问
@Authorize(policy = AuthorizePolicy.Authenticated) //要求已经登录才能访问 默认为该注解

Swagger

接口支持Swagger注解 开发可以根据需求 考虑是否需要远程调用调试

以下参数 非接口必要参数 根据情况自行调整

@Api

@Api 注解用于标识一个类是 Swagger 的资源。通常，这个注解用在控制器类上，用于描述该控制器所提供的 API

@Api(value = "用户管理", tags = "用户相关的操作")
@RestController
@RequestMapping("/api/users")
public class UserController {
    // ...
}

@ApiOperation

@ApiOperation注解用于描述一个 API 方法的功能。它提供了方法的简要描述、可能的返回值以及 HTTP 操作的类型

@GetMapping("/{id}")
@ApiOperation(value = "根据ID获取用户", notes = "根据提供的用户ID返回用户信息")
public User getUserById(@PathVariable String id) {
    // ...
}

@ApiParam

@ApiParam 注解用于描述 API 方法参数的详细信息，包括参数的名称、类型、是否必需、默认值等

@GetMapping("/{id}")
@ApiOperation(value = "根据ID获取用户", notes = "根据提供的用户ID返回用户信息")
public User getUserById(@PathVariable String id) {
    // ...
}

@ApiResponse

@ApiResponse 注解用于描述 API 方法可能返回的响应信息，通常与 @ApiOperation一起使用。可以定义响应的 HTTP 状态码、描述和返回类型

@ApiOperation(value = "获取用户列表")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "成功获取用户列表"),
    @ApiResponse(code = 404, message = "用户未找到")
})
@GetMapping
public List<User> getAllUsers() {
    // ...
}

登录

柔性设计平台接口需要访问数据库信息或者是用户信息时 要求 存在登录信息

下面介绍接口实现登录的方法 具体使用LoginHelper 类

LoginHelper 登录类

• login(userId, password, clientInfo, dataArea)：登录 参数分别为 用户编号 密码 客户端信息（一般为null） 账套

      @GetMapping("/login")
      public String loginByUser(String userId,String password) {
          UserSession userSession = LoginHelper.login(userId, password, null, "dynamic");
          if(userSession ==null  || UserSession.current() ==null) {
              return ResultUtil.errorResult("用户名密码错误 登录失败");
          }
          return ResultUtil.successResult(UserSession.current().getUserSessionId());
      }
  

• LoginHelper.loginByCode(code, userIdFunction) ：根据code 登录 在 function 根据传入的code 找到对应的 userId 返回 则可登录该用户

      @GetMapping("/loginByCode")
      public String loginByCode(String code) {
          LoginHelper.loginByCode(code, new Function<String, String>() {
              @Override
              public String apply(String code) {
                  SysUser sysUser = DAOHelper.findRecord(SysUser.class, SysUser._Weixin,code);
                  if(sysUser !=null) {
                      return sysUser.getUserId();
                  }
                  return null;
              }
          });
          if( UserSession.current() ==null) {
              return ResultUtil.errorResult("Code验证异常 登录失败");
          }
          return ResultUtil.successResult(UserSession.current().getUserSessionId());
      }
  

• LoginHelper.loginByToken(token, clientInfo, dataArea)：根据token登录

    @GetMapping("/loginByToken")
    public String loginByToken(String token) {
        LoginHelper.loginByToken(token, null, "dynamic");
        if( UserSession.current() ==null) {
            return ResultUtil.errorResult("Code验证异常 登录失败");
        }
        return ResultUtil.successResult(UserSession.current().getUserSessionId());
    }
  

请求地址

根据环境不同 请求路径存在差异

域环境

开发环境根据接口位置不同 路径不同

• 层：http://ip:port/GongqiERP/web/xxxx 例如一个在 ent的登录接口路径为 http://127.0.0.1:10108/GongqiERP/web/user/login
• 应用：http://ip:port/web/apps/appId/xxxx 例如在销售管理应用的一个获取订单数据接口路径 http://127.0.0.1:10108/web/apps/gongqi.df.sales/getSalasTable
• 插件：http://ip:port/web/apps/plgId/xxxx 例如在销售管理应用上的一个绑定插件 获取数据接口路径 http://127.0.0.1:10108/web/apps/gongqi.pl.salesmen/getPlgData
• 扩展：http://ip:port/web/apps/appId/xxxx 例如在销售管理扩展 的一个获取订单数据接口路径 http://127.0.0.1:10108/web/apps/gongqi.df.sales/getExtSalasTable

OS环境

os环境 比 域环境多了一层 如果是web请求 则在域 接口路径前 把ip 端口换成 osIP端口 且在web前面拼上 域Id

如 请求一个 Item 物料域的 gongqi.eqm.ims 应用的 接口

http://os-kf.gongqi.info/Item/web/apps/gongqi.eqm.ims/configuration/getFileDraw