JeecgBoot/JimuReport 在线填报功能自定义API接口404问题解析

问题背景

在使用JeecgBoot/JimuReport报表系统的在线填报功能时，开发者可能会遇到自定义API接口返回404错误的问题。这种情况通常发生在开发者按照文档编写了自定义接口，但系统却无法正确访问该接口。

问题现象

开发者创建了一个名为OlineWriteApiController的控制器类，其中包含两个方法：

1. queryFormData方法用于查询表单数据
2. submitFormData方法用于提交表单数据

虽然日志显示请求确实到达了控制器方法（可以看到日志输出），但系统仍然返回404错误，提示接口不存在。

问题根源分析

经过深入分析，发现问题的根本原因在于控制器类的注解使用不当。原代码中使用了@Controller注解，而没有使用@RestController或@ResponseBody注解。

在Spring框架中：

• @Controller注解通常用于返回视图名称，适用于传统的MVC模式
• @RestController是@Controller和@ResponseBody的组合注解，专门用于RESTful API开发
• 当使用@Controller时，方法默认返回的是视图名称，而不是JSON数据

解决方案

要解决这个问题，有以下两种修改方案：

方案一：使用@RestController替换@Controller

@RestController
@RequestMapping("/onlineWrite")
public class OlineWriteApiController {
    // 方法实现保持不变
}

方案二：保留@Controller但添加@ResponseBody

@Controller
@RequestMapping("/onlineWrite")
public class OlineWriteApiController {
    
    @ResponseBody
    @GetMapping("/submit/handle")
    public Result<?> queryFormData(@RequestParam List<String> dataIds) {
        // 方法实现
    }

    @ResponseBody
    @PostMapping("/submit/handle")
    public Result<?> submitFormData(@RequestBody Map<String,Object> data) {
        // 方法实现
    }
}

技术原理

在Spring MVC中，当使用@Controller注解时：

1. 方法返回值会被解析为视图名称
2. 需要配合视图解析器来渲染视图
3. 如果不返回视图而想返回JSON数据，必须显式添加@ResponseBody

而@RestController注解：

1. 是@Controller和@ResponseBody的组合
2. 自动将方法返回值序列化为JSON
3. 专为RESTful API设计
4. 不需要额外的视图解析配置

最佳实践建议

1. 统一使用@RestController：对于纯API接口，建议统一使用@RestController，代码更简洁
2. 接口测试：开发完成后，使用Postman等工具测试接口是否可访问
3. 日志监控：在关键位置添加日志输出，便于问题排查
4. 异常处理：添加全局异常处理，返回统一的错误格式
5. API文档：使用Swagger等工具生成API文档，便于前后端协作

总结

在JeecgBoot/JimuReport项目中实现自定义API接口时，正确选择控制器注解至关重要。对于返回JSON数据的RESTful接口，应当优先使用@RestController注解，这样可以避免因注解使用不当导致的404错误。理解Spring MVC中不同注解的差异和适用场景，能够帮助开发者更高效地构建稳定的API接口。