Apache HertzBeat RESTful API全攻略：二次开发必备-优快云博客

Apache HertzBeat RESTful API全攻略：二次开发必备

在现代监控系统中，API接口是连接用户与系统核心功能的桥梁。Apache HertzBeat作为一款功能强大的实时监控系统，提供了丰富的RESTful API接口，为二次开发提供了极大的灵活性。本文将详细介绍HertzBeat的RESTful API体系，帮助开发者快速上手并实现自定义功能。

API架构概览

HertzBeat的API系统采用分层架构设计，主要包含控制器层、服务层和数据访问层。控制器层负责处理HTTP请求，服务层实现业务逻辑，数据访问层负责与数据库交互。这种分层设计保证了系统的可扩展性和可维护性。

核心API模块位于manager/src/main/java/org/apache/hertzbeat/manager/controller目录下，包含多个控制器类，分别处理不同类型的API请求。主要控制器包括：

MonitorController.java：处理单个监控任务的CRUD操作
MonitorsController.java：处理批量监控任务的管理
MetricsController.java：处理指标相关的API请求
StatusPageController.java：处理状态页面相关操作

认证与授权

HertzBeat的API接口需要进行认证授权才能访问。认证通过JWT（JSON Web Token）实现，用户登录成功后获取token，后续请求在HTTP头部携带token即可。

认证相关的代码实现位于AccountController.java，主要提供登录和刷新token的接口：

@PostMapping("/login")
@Operation(summary = "User login", description = "User login to get access token")
public ResponseEntity<Message<LoginResponse>> login(@Valid @RequestBody LoginRequest loginRequest) {
    // 登录逻辑实现
}

@PostMapping("/refresh")
@Operation(summary = "Refresh token", description = "Refresh access token with refresh token")
public ResponseEntity<Message<RefreshTokenResponse>> refreshToken(@RequestBody RefreshTokenRequest request) {
    // 刷新token逻辑实现
}

监控管理API详解

监控管理是HertzBeat的核心功能，提供了丰富的API接口来管理监控任务。主要分为单个监控管理和批量监控管理两类接口。

单个监控管理API

MonitorController.java提供了单个监控任务的完整生命周期管理接口：

添加监控

@PostMapping
@Operation(summary = "Add a monitoring application", description = "Add a monitoring application")
public ResponseEntity<Message<Void>> addNewMonitor(@Valid @RequestBody MonitorDto monitorDto) {
    // 验证请求数据
    monitorService.validate(monitorDto, false);
    monitorService.addMonitor(monitorDto.getMonitor(), monitorDto.getParams(), monitorDto.getCollector());
    return ResponseEntity.ok(Message.success("Add success"));
}

请求示例：

{
  "monitor": {
    "name": "Linux Server Monitor",
    "app": "linux",
    "host": "192.168.1.100",
    "interval": 10,
    "timeout": 3000,
    "status": 1
  },
  "params": [
    {"key": "username", "value": "admin"},
    {"key": "password", "value": "password"}
  ],
  "collector": "default"
}

修改监控

@PutMapping
@Operation(summary = "Modify an existing monitoring application", description = "Modify an existing monitoring application")
public ResponseEntity<Message<Void>> modifyMonitor(@Valid @RequestBody MonitorDto monitorDto) {
    // 验证请求数据
    monitorService.validate(monitorDto, true);
    monitorService.modifyMonitor(monitorDto.getMonitor(), monitorDto.getParams(), monitorDto.getCollector());
    return ResponseEntity.ok(Message.success("Modify success"));
}

获取监控详情

@GetMapping(path = "/{id}")
@Operation(summary = "Obtain monitoring information based on monitoring ID", description = "Obtain monitoring information based on monitoring ID")
public ResponseEntity<Message<MonitorDto>> getMonitor(
        @Parameter(description = "Monitoring task ID", example = "6565463543") @PathVariable("id") final long id) {
    // 获取监控信息
    MonitorDto monitorDto = monitorService.getMonitorDto(id);
    if (monitorDto == null) {
        return ResponseEntity.ok(Message.fail(MONITOR_NOT_EXIST_CODE, "Monitor not exist."));
    } else {
        return ResponseEntity.ok(Message.success(monitorDto));
    }
}

删除监控

@DeleteMapping(path = "/{id}")
@Operation(summary = "Delete monitoring application based on monitoring ID", description = "Delete monitoring application based on monitoring ID")
public ResponseEntity<Message<Void>> deleteMonitor(
        @Parameter(description = "en: Monitor ID", example = "6565463543") @PathVariable("id") final long id) {
    // 删除监控
    Monitor monitor = monitorService.getMonitor(id);
    if (monitor == null) {
        return ResponseEntity.ok(Message.success("The specified monitoring was not queried, please check whether the parameters are correct"));
    }
    monitorService.deleteMonitor(id);
    return ResponseEntity.ok(Message.success("Delete success"));
}

批量监控管理API

MonitorsController.java提供了批量管理监控任务的接口：

批量获取监控列表

@GetMapping
@Operation(summary = "Obtain a list of monitoring information based on query filter items",
        description = "Obtain a list of monitoring information based on query filter items")
public ResponseEntity<Message<Page<Monitor>>> getMonitors(
        @Parameter(description = "Monitor ID", example = "6565463543") @RequestParam(required = false) final List<Long> ids,
        @Parameter(description = "Monitor Type", example = "linux") @RequestParam(required = false) final String app,
        @Parameter(description = "Monitor Name support fuzzy query", example = "linux-127.0.0.1") @RequestParam(required = false) final String name,
        @Parameter(description = "Monitor Host support fuzzy query", example = "127.0.0.1") @RequestParam(required = false) final String host,
        @Parameter(description = "Monitor Status 0:no monitor,1:usable,2:disabled,9:all status", example = "1") @RequestParam(required = false) final Byte status,
        @Parameter(description = "Sort Field ", example = "name") @RequestParam(defaultValue = "gmtCreate") final String sort,
        @Parameter(description = "Sort mode eg:asc desc", example = "desc") @RequestParam(defaultValue = "desc") final String order,
        @Parameter(description = "List current page", example = "0") @RequestParam(defaultValue = "0") int pageIndex,
        @Parameter(description = "Number of list pagination ", example = "8") @RequestParam(defaultValue = "8") int pageSize,
        @Parameter(description = "Monitor tag ", example = "env:prod") @RequestParam(required = false) final String tag) {
    Page<Monitor> monitorPage = monitorService.getMonitors(ids, app, name, host, status, sort, order, pageIndex, pageSize, tag);
    return ResponseEntity.ok(Message.success(monitorPage));
}

批量删除监控

@DeleteMapping
@Operation(summary = "Delete monitoring items in batches according to the monitoring ID list",
        description = "Delete monitoring items in batches according to the monitoring ID list")
public ResponseEntity<Message<Void>> deleteMonitors(
        @Parameter(description = "Monitoring ID List", example = "6565463543") @RequestParam(required = false) List<Long> ids
) {
    if (ids != null && !ids.isEmpty()) {
        monitorService.deleteMonitors(new HashSet<>(ids));
    }
    return ResponseEntity.ok(Message.success());
}

监控配置导入导出

HertzBeat支持监控配置的导入导出功能，方便在不同环境间迁移监控配置：

@GetMapping("/export")
@Operation(summary = "export monitor config", description = "export monitor config")
public void export(
        @Parameter(description = "Monitor ID List", example = "6565463543") @RequestParam List<Long> ids,
        @Parameter(description = "Export Type:JSON,EXCEL,YAML") @RequestParam(defaultValue = "JSON") String type,
        HttpServletResponse res) throws Exception {
    monitorService.export(ids, type, res);
}

@PostMapping("/import")
@Operation(summary = "import monitor config", description = "import monitor config")
public ResponseEntity<Message<Void>> export(MultipartFile file) throws Exception {
    monitorService.importConfig(file);
    return ResponseEntity.ok(Message.success("Import success"));
}

指标数据API

指标数据是监控系统的核心产出，HertzBeat提供了多种API接口来获取和导出指标数据。

获取监控指标

MetricsController.java提供了获取系统内部指标的接口：

@GetMapping()
@Operation(summary = "Get Hertzbeat Metrics Data")
public ResponseEntity<Message<Map<String, Object>>> getMetricsInfo() {
    Map<String, Object> metricsInfo = new HashMap<>(8);
    if (commonDataQueue instanceof InMemoryCommonDataQueue dataQueue) {
        Map<String, Integer> queueInfo = dataQueue.getQueueSizeMetricsInfo();
        metricsInfo.putAll(queueInfo);
    }
    return ResponseEntity.ok(Message.success(metricsInfo));
}

获取监控指标定义

MonitorController.java提供了获取特定应用类型可监控指标的接口：

@GetMapping(value = {"/metric/{app}", "/metric"})
@Operation(summary = "get app metric", description = "Obtain indicators that can be monitored by the app based on the app name")
public ResponseEntity<Message<List<String>>> getMonitorMetrics(
        @PathVariable(value = "app", required = false) String app) {
    List<String> metricNames = monitorService.getMonitorMetrics(app);
    return ResponseEntity.ok(Message.success(metricNames));
}

状态页面API

HertzBeat提供了状态页面功能，可以将监控状态以友好的方式展示给用户。StatusPageController.java提供了相关的API接口：

@PostMapping("/org")
@Operation(summary = "Create or update status page organization information", description = "Create or update status page organization information")
public ResponseEntity<Message<StatusPageOrg>> saveStatusPageOrg(@Valid @RequestBody StatusPageOrg statusPageOrg) {
    return ResponseEntity.ok(Message.success(statusPageService.saveStatusPageOrg(statusPageOrg)));
}

@GetMapping("/org")
@Operation(summary = "Get status page organization information", description = "Get status page organization information")
public ResponseEntity<Message<StatusPageOrg>> getStatusPageOrg() {
    return ResponseEntity.ok(Message.success(statusPageService.queryStatusPageOrg()));
}

插件管理API

HertzBeat支持插件扩展，PluginController.java提供了插件管理的相关接口：

@PostMapping
@Operation(summary = "Upload plugin package", description = "Upload plugin package")
public ResponseEntity<Message<Void>> uploadPlugin(@RequestParam("file") MultipartFile file) {
    pluginService.savePlugin(file);
    return ResponseEntity.ok(Message.success("Upload success"));
}

@GetMapping
@Operation(summary = "Get plugin list", description = "Get all plugin list")
public ResponseEntity<Message<List<PluginMetadata>>> getPlugins() {
    return ResponseEntity.ok(Message.success(pluginService.getPlugins()));
}

API调用示例

下面以添加Linux监控为例，展示完整的API调用流程：

登录获取token

curl -X POST http://localhost:1157/api/account/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"hertzbeat"}'

返回结果：

{
  "code": 0,
  "msg": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}

添加Linux监控

curl -X POST http://localhost:1157/api/monitor \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "monitor": {
      "name": "Linux Server",
      "app": "linux",
      "host": "192.168.1.100",
      "interval": 10,
      "timeout": 3000,
      "status": 1
    },
    "params": [
      {"key": "username", "value": "root"},
      {"key": "password", "value": "password"},
      {"key": "port", "value": "22"}
    ],
    "collector": "default"
  }'

获取监控列表

curl -X GET "http://localhost:1157/api/monitors?app=linux" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

二次开发最佳实践

API版本控制

HertzBeat的API目前没有显式的版本控制，但为了保证兼容性，建议在二次开发时注意以下几点：

密切关注官方发布的更新日志，了解API变更情况
在调用API时，尽量指定具体的参数，避免依赖默认值
实现API调用的错误处理机制，当API变更时能够及时发现

性能优化

批量操作优先：对于大量监控任务的管理，优先使用批量API，减少请求次数
合理设置分页：获取监控列表时，使用分页参数控制返回数据量
异步处理：对于耗时操作（如批量导入导出），采用异步方式处理

安全性考虑

HTTPS：生产环境中务必启用HTTPS，保护API通信安全
权限控制：根据实际需求为不同用户分配适当的API访问权限
请求频率限制：实现API请求频率限制，防止恶意请求攻击

总结

Apache HertzBeat提供了全面的RESTful API接口，覆盖了监控管理、指标收集、状态页面、插件管理等各个方面。通过这些API，开发者可以灵活地扩展HertzBeat的功能，实现自定义的监控需求。

官方文档：home/docs/

API源码：manager/src/main/java/org/apache/hertzbeat/manager/controller/

社区教程：README.md

希望本文能够帮助开发者更好地理解和使用HertzBeat的API接口，开发出更强大的监控解决方案。如有任何问题，欢迎在社区交流讨论。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考