Spring Boot 与 TDengine 的深度集成实践（三）

创建 RESTful API

编写控制器类

在 Spring Boot 项目中，控制器类负责处理 HTTP 请求，并将请求转发到相应的服务或数据访问层进行处理，最后返回响应结果给客户端。我们通过使用@RestController和@RequestMapping注解来定义控制器类和 API 路由 。

在src/main/java/com/example/springboottdengineintegration/controller目录下创建一个控制器类，例如SensorDataController：

package com.example.springboottdengineintegration.controller;

import com.example.springboottdengineintegration.entity.SensorData;

import com.example.springboottdengineintegration.service.SensorDataService;

import org.springframework.http.HttpStatus;

import org.springframework.http.ResponseEntity;

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

import java.util.List;

@RestController

@RequestMapping("/api/sensor-data")

public class SensorDataController {

private final SensorDataService sensorDataService;

public SensorDataController(SensorDataService sensorDataService) {

this.sensorDataService = sensorDataService;

}

在上述代码中：

• @RestController注解表明该类是一个 RESTful 风格的控制器，它是@Controller和@ResponseBody的组合注解，@Controller用于标识该类是一个控制器组件，会被 Spring 容器扫描并管理，@ResponseBody则表示该类中所有方法的返回值会直接作为 HTTP 响应体返回给客户端，而不会被解析为视图名，适用于返回 JSON、XML 等数据格式的场景 。

• @RequestMapping("/api/sensor-data")注解用于映射 HTTP 请求的 URL 路径，它可以作用于类和方法上。这里作用于类上，表示该控制器类下的所有方法的 URL 路径都以/api/sensor-data为前缀 。例如，访问/api/sensor-data路径下的某个具体方法时，完整的 URL 将是http://localhost:8080/api/sensor-data/具体方法路径，其中8080是 Spring Boot 应用默认的端口号，可在application.properties或application.yml文件中进行修改 。

实现 CRUD 操作

接下来，在SensorDataController控制器类中实现数据的增删改查（CRUD）操作，这些操作将调用SensorDataService服务层中的方法来与 TDengine 数据库进行交互 。

// 获取所有传感器数据

@GetMapping

public ResponseEntity<List<SensorData>> getAllSensorData() {

List<SensorData> sensorDataList = sensorDataService.getAllSensorData();

return new ResponseEntity<>(sensorDataList, HttpStatus.OK);

}

// 根据ID获取传感器数据

@GetMapping("/{id}")

public ResponseEntity<SensorData> getSensorDataById(@PathVariable int id) {

return sensorDataService.getSensorDataById(id)

.map(ResponseEntity::ok)

.orElse(ResponseEntity.notFound().build());

}

// 创建新的传感器数据

@PostMapping

public ResponseEntity<SensorData> createSensorData(@RequestBody SensorData sensorData) {

SensorData savedSensorData = sensorDataService.createSensorData(sensorData);

return new ResponseEntity<>(savedSensorData, HttpStatus.CREATED);

}

// 更新传感器数据

@PutMapping("/{id}")

public ResponseEntity<SensorData> updateSensorData(@PathVariable int id, @RequestBody SensorData sensorData) {

return sensorDataService.updateSensorData(id, sensorData)

.map(ResponseEntity::ok)

.orElse(ResponseEntity.notFound().build());

}

// 删除传感器数据

@DeleteMapping("/{id}")

public ResponseEntity<Void> deleteSensorData(@PathVariable int id) {

boolean deleted = sensorDataService.deleteSensorData(id);

if (deleted) {

return new ResponseEntity<>(HttpStatus.NO_CONTENT);

} else {

return new ResponseEntity<>(HttpStatus.NOT_FOUND);

}

}

在上述代码中：

• 获取所有传感器数据：

• • @GetMapping注解用于映射 HTTP GET 请求，当客户端发送 GET 请求到/api/sensor-data路径时，会调用该方法 。

• • sensorDataService.getAllSensorData()方法用于从数据库中获取所有的传感器数据，返回一个SensorData类型的列表 。

• • new ResponseEntity<>(sensorDataList, HttpStatus.OK)创建一个 HTTP 响应实体，将获取到的传感器数据列表作为响应体，并设置 HTTP 状态码为200 OK，表示请求成功 。

• 根据 ID 获取传感器数据：

• • @GetMapping("/{id}")注解映射的 URL 路径中包含一个占位符{id}，表示该路径是一个动态路径，其中{id}会被实际的 ID 值替换 。例如，访问/api/sensor-data/1路径时，1就是实际的 ID 值 。

• • @PathVariable int id用于将 URL 路径中的id值绑定到方法参数id上，这样在方法内部就可以使用该 ID 值进行数据库查询 。

• • sensorDataService.getSensorDataById(id)方法根据传入的 ID 从数据库中查询传感器数据，返回一个Optional<SensorData>类型的结果 。Optional是 Java 8 引入的一个容器类，用于解决空指针异常问题，它可以包含一个非空值或者为空 。

• • map(ResponseEntity::ok)方法将Optional<SensorData>中的值转换为一个 HTTP 响应实体，状态码为200 OK；orElse(ResponseEntity.notFound().build())方法表示如果Optional为空，则返回一个状态码为404 Not Found的 HTTP 响应实体，表示未找到对应 ID 的数据 。

• 创建新的传感器数据：

• • @PostMapping注解用于映射 HTTP POST 请求，当客户端发送 POST 请求到/api/sensor-data路径时，会调用该方法 。

• • @RequestBody SensorData sensorData用于将 HTTP 请求体中的 JSON 数据转换为SensorData对象，Spring Boot 会自动根据请求体中的数据填充SensorData对象的属性 。

• • sensorDataService.createSensorData(sensorData)方法将接收到的SensorData对象保存到数据库中，并返回保存后的SensorData对象 。

• • new ResponseEntity<>(savedSensorData, HttpStatus.CREATED)创建一个 HTTP 响应实体，将保存后的传感器数据作为响应体，并设置 HTTP 状态码为201 Created，表示资源已成功创建 。

• 更新传感器数据：

• • @PutMapping("/{id}")注解映射 HTTP PUT 请求，用于更新资源，当客户端发送 PUT 请求到/api/sensor-data/{id}路径时，会调用该方法 。

• • @PathVariable int id获取 URL 路径中的 ID 值，@RequestBody SensorData sensorData获取请求体中的更新数据 。

• • sensorDataService.updateSensorData(id, sensorData)方法根据传入的 ID 和更新后的SensorData对象，在数据库中更新对应的数据，并返回更新后的SensorData对象（如果更新成功） 。

• • 同样，使用map(ResponseEntity::ok)和orElse(ResponseEntity.notFound().build())方法来处理更新结果，返回相应的 HTTP 响应实体 。

• 删除传感器数据：

• • @DeleteMapping("/{id}")注解映射 HTTP DELETE 请求，当客户端发送 DELETE 请求到/api/sensor-data/{id}路径时，会调用该方法 。

• • sensorDataService.deleteSensorData(id)方法根据传入的 ID 从数据库中删除对应的数据，并返回一个布尔值表示删除操作是否成功 。

• • 根据删除结果，返回不同的 HTTP 响应实体。如果删除成功，返回状态码为204 No Content的响应实体，表示请求成功处理，但没有返回内容；如果删除失败（未找到对应 ID 的数据），返回状态码为404 Not Found的响应实体 。

通过以上步骤，我们在 Spring Boot 项目中成功创建了一个 RESTful API，实现了对 TDengine 数据库中传感器数据的增删改查操作 。这些 API 接口可以方便地与前端应用或其他后端服务进行交互，为业务系统提供数据支持 。

测试 API

使用 Postman 测试

在完成 RESTful API 的开发后，我们需要对其进行测试，以确保 API 的功能正常，能够正确地与 TDengine 数据库进行交互并返回预期的结果。Postman 是一款常用的 API 测试工具，它提供了简洁直观的界面，方便我们发送各种 HTTP 请求，并查看响应结果 。

1. 启动 Spring Boot 应用：在 IDE 中，右键点击 Spring Boot 项目的启动类SpringBootTdengineIntegrationApplication，选择 “Run 'SpringBootTdengineIntegrationApplication'”，启动 Spring Boot 应用 。启动成功后，控制台会显示应用的启动信息，包括应用的端口号（默认为 8080），例如：

. ____ _ __ _ _

/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \

( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \

\\/ ___)| |_)| | | | | || (_| | ) ) ) )

' |____|.__|_| |_|_| |_\__, | / / / /

=========|_|==============|___/=/_/_/_/

:: Spring Boot :: (v3.2.0)

2024-11-12 15:30:15.678 INFO 12345 --- [ main] c.e.s.SpringBootTdengineIntegrationApplication : Starting SpringBootTdengineIntegrationApplication using Java 11.0.11 on your-computer-name with PID 12345 (/path/to/your/project/target/spring-boot-tdengine-integration-0.0.1-SNAPSHOT.jar started by your-username in /path/to/your/project)

2024-11-12 15:30:15.681 INFO 12345 --- [ main] c.e.s.SpringBootTdengineIntegrationApplication : No active profile set, falling back to 1 default profile: "default"

2024-11-12 15:30:16.782 INFO 12345 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)

2024-11-12 15:30:16.800 INFO 12345 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]

2024-11-12 15:30:16.800 INFO 12345 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/10.1.11]

2024-11-12 15:30:16.943 INFO 12345 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext

2024-11-12 15:30:16.943 INFO 12345 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1196 ms

2024-11-12 15:30:17.663 INFO 12345 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path ''

2024-11-12 15:30:17.673 INFO 12345 --- [ main] c.e.s.SpringBootTdengineIntegrationApplication : Started SpringBootTdengineIntegrationApplication in 2.344 seconds (process running for 3.058)

1. 打开 Postman：在 Postman 中，点击 “New” 按钮，选择 “Request”，创建一个新的请求 。

1. 测试获取所有传感器数据的 API：

• • 在请求方法下拉框中选择 “GET”。

• • 在请求 URL 输入框中输入http://localhost:8080/api/sensor-data，这里的localhost是本地主机地址，8080是 Spring Boot 应用的端口号，/api/sensor-data是我们在控制器类中定义的 API 路径 。

• • 点击 “Send” 按钮发送请求。如果 API 正常工作，Postman 会显示 HTTP 状态码为 200 OK 的响应，响应体中会包含从 TDengine 数据库中查询到的所有传感器数据，例如：

[

{

"id": 1,

"sensorId": "sensor1",

"value": 25.5,

"timestamp": 1634567890000

},

{

"id": 2,

"sensorId": "sensor2",

"value": 30.2,

"timestamp": 1634567900000

}

]

1. 测试根据 ID 获取传感器数据的 API：

• • 在请求方法下拉框中仍选择 “GET”。

• • 在请求 URL 输入框中输入http://localhost:8080/api/sensor-data/1，其中1是要查询的传感器数据的 ID 。

• • 点击 “Send” 按钮发送请求。如果数据库中存在 ID 为 1 的记录，Postman 会显示状态码为 200 OK 的响应，响应体中包含该条传感器数据；如果不存在，会显示状态码为 404 Not Found 的响应 。

1. 测试创建新的传感器数据的 API：

• • 在请求方法下拉框中选择 “POST”。

• • 在请求 URL 输入框中输入http://localhost:8080/api/sensor-data。

• • 在请求体（Body）选项卡中，选择 “raw”，并将数据格式设置为 “JSON (application/json)”，然后输入要创建的传感器数据，例如：

{

"sensorId": "sensor3",

"value": 28.7,

"timestamp": 1634567910000

}

• 点击 “Send” 按钮发送请求。如果创建成功，Postman 会显示状态码为 201 Created 的响应，响应体中包含创建的传感器数据 。

1. 测试更新传感器数据的 API：

• • 在请求方法下拉框中选择 “PUT”。

• • 在请求 URL 输入框中输入http://localhost:8080/api/sensor-data/1，这里的1是要更新的传感器数据的 ID 。

• • 在请求体（Body）选项卡中，输入更新后的传感器数据，例如：

{

"sensorId": "sensor1",

"value": 26.0,

"timestamp": 1634567920000

}

• 点击 “Send” 按钮发送请求。如果更新成功，Postman 会显示状态码为 200 OK 的响应，响应体中包含更新后的传感器数据；如果未找到对应 ID 的数据，会显示状态码为 404 Not Found 的响应 。

1. 测试删除传感器数据的 API：

• • 在请求方法下拉框中选择 “DELETE”。

• • 在请求 URL 输入框中输入http://localhost:8080/api/sensor-data/1，这里的1是要删除的传感器数据的 ID 。

• • 点击 “Send” 按钮发送请求。如果删除成功，Postman 会显示状态码为 204 No Content 的响应，表示请求成功处理，但没有返回内容；如果未找到对应 ID 的数据，会显示状态码为 404 Not Found 的响应 。

测试结果分析

通过使用 Postman 对各个 API 进行测试，我们可以根据测试结果来分析 API 的运行情况，判断是否达到预期的功能。在测试过程中，可能会遇到以下一些问题及解决方法：

• HTTP 状态码异常：

• • 404 Not Found：表示请求的资源未找到，可能是 API 路径错误。需要仔细检查请求 URL 中的路径是否与控制器类中定义的路径一致，包括大小写、斜杠等。例如，如果控制器类中定义的路径是/api/sensor-data，而请求 URL 中写成了/api/Sensor-Data，就会导致 404 错误，因为 URL 路径是区分大小写的 。

• • 500 Internal Server Error：表示服务器内部发生错误，可能是代码中出现了异常。需要查看 Spring Boot 应用的控制台日志，找到异常信息，分析错误原因。例如，如果在 DAO 层的查询方法中出现了 SQL 语法错误，就会导致 500 错误，此时需要检查 SQL 语句的正确性，包括表名、字段名、语法结构等 。

• 响应数据不正确：

• • 数据缺失：如果响应体中缺少某些字段或数据不完整，可能是实体类与数据库表的映射出现问题，或者在查询或保存数据时出现了错误。需要检查实体类的注解是否正确，以及 DAO 层和服务层的代码逻辑 。例如，如果实体类中某个字段的注解错误，导致该字段无法正确映射到数据库表中，那么在查询数据时就可能会出现该字段缺失的情况 。

• • 数据错误：如果响应数据与预期不符，可能是业务逻辑错误或数据处理错误。需要检查服务层和控制器层的代码，确保数据的处理和返回符合业务需求 。例如，在更新数据的方法中，如果更新逻辑错误，可能会导致返回的更新后的数据与实际更新的数据不一致 。

• 请求参数问题：

• • 参数格式错误：如果请求体中的 JSON 数据格式不正确，会导致服务器无法正确解析参数，从而返回错误响应。需要确保请求体中的 JSON 数据符合 JSON 语法规范，例如，键值对必须用双引号括起来，字符串值也必须用双引号括起来等 。例如，以下是一个错误的 JSON 格式：{sensorId: "sensor1", value: 25.5, timestamp: 1634567890000}，正确的格式应该是{"sensorId": "sensor1", "value": 25.5, "timestamp": 1634567890000} 。

• • 参数缺失：如果请求中缺少必要的参数，也会导致 API 无法正常工作。需要仔细检查 API 的文档或代码，确定每个 API 所需的参数，并在请求中正确传递 。例如，创建传感器数据的 API 需要传递sensorId、value和timestamp三个参数，如果请求体中缺少其中任何一个参数，都会导致创建失败 。

通过对测试结果的分析和问题的解决，我们可以确保 Spring Boot 与 TDengine 集成项目中的 RESTful API 能够稳定、正确地运行，为后续的业务开发提供可靠的数据接口 。