TDengine 与 taosAdapter 的结合（一）

一、引言

在当今数字化时代，数据量呈爆发式增长，尤其是物联网、工业互联网等领域产生的海量时序数据，对数据存储和处理提出了极高要求。TDengine 作为一款高性能、开源的时序数据库，专为这些场景设计并优化，在时序数据库领域占据着重要地位。它具有极强的弹性伸缩能力，带有内建的缓存、流式计算、数据订阅等系统功能，能大幅减少系统设计的复杂度，降低研发和运营成本 。

然而，在实际应用开发中，为了更方便地与各类应用程序集成，RESTful 接口成为了一种广泛使用的方式。taosAdapter 作为 TDengine 与应用程序之间的桥梁，就发挥了重要作用。它支持用户通过 RESTful 接口和 WebSocket 连接访问 TDengine 服务，实现数据的便捷接入和处理。通过 taosAdapter，TDengine 能够与各种数据收集代理工具（如 Telegraf、StatsD、collectd 等）无缝对接，还提供了与 InfluxDB/OpenTSDB 兼容的数据写入接口，使得原本使用 InfluxDB/OpenTSDB 的应用程序能够轻松移植到 TDengine 上，无须进行大量修改。

本文将深入探讨如何在 RESTful 接口开发中，实现 TDengine 与 taosAdapter 的有效结合，通过详细的步骤和示例代码，帮助开发者快速掌握这一技术，充分发挥 TDengine 在时序数据处理方面的强大优势。

二、TDengine 与 taosAdapter 基础介绍

（一）TDengine 简介

TDengine 是一款高性能、分布式、支持 SQL 的时序数据库，专为物联网、车联网、工业互联网、IT 运维等场景设计并优化。它具备诸多显著特点，使其在时序数据处理领域脱颖而出。

• 高性能：TDengine 采用了创新的存储引擎设计，通过使用异步 IO、内存映射文件和数据压缩等技术，以及对查询语句的优化 ，实现了高速的数据写入和查询。其性能比通用数据库快 10 倍以上，也远超其他时序数据库，并且在存储空间上也有显著的节省。例如，在处理物联网设备每秒产生的大量数据时，TDengine 能够轻松应对高并发写入，确保数据的及时存储，同时在进行历史数据查询分析时，能快速返回结果，满足业务实时性需求。

• 分布式架构：从诞生之初就以水平扩展和高可用为核心设计理念，采用分布式架构。通过虚拟节点（vnode）技术，将集群内的多个物理节点划分为多个 vnode，每个 vnode 存储特定的数据采集点的数据，一个数据采集点的数据只存放在一个 vnode 内 。这种设计实现了写入和查询时的水平扩展，客户端可以将数据直接写入对应的 vnode，集群节点数越多，系统的吞吐能力越强；对于聚合查询，首先在各个 vnode 内完成初步聚合，客户端再进行二次聚合，降低了查询聚合的复杂度。此外，还支持按时间段对数据进行分区，如按天、按周等用户定义的时间范围，方便实现数据保留策略和冷热数据分离，减少存储成本。通过虚拟节点组技术保障系统高可用性，虚拟节点组内的数据采用 Leader - Follower 模式同步，当 Leader 节点发生故障时，系统会自动选举新的 Leader，确保数据访问不中断，并实现故障转移。

• 支持 SQL：采用 SQL 作为数据查询语言，这使得熟悉 SQL 的开发者可以轻松上手，减少了学习和迁移成本。同时，它还提供了 SQL 扩展来处理时序数据特有的分析，支持方便灵活的 schemaless 数据写入，进一步提升了数据操作的便捷性。

• All in One：将数据库、消息队列、缓存、流式计算等功能融合在一起，应用无需再集成 Kafka/Redis/HBase/Spark 等软件，大幅降低了应用开发和维护成本。例如，在工业互联网场景中，设备产生的数据可以直接写入 TDengine，同时利用其内置的流式计算功能进行实时数据分析，通过消息队列实现数据的分发，而无需额外搭建复杂的技术栈。

• 零管理与零学习成本：安装、集群搭建简单，几秒即可完成，并且无任何依赖，不用分库分表。它提供了简单的接口、极简的解决方案和与第三方工具的无缝集成，同时支持 C/C++、Python、Java、Go、Rust、Node.js 等多种编程语言，与 MySQL 相似，开发者几乎零学习成本。

TDengine 的应用场景极为广泛，涵盖物联网数据存储和分析、车联网数据处理、工业物联网设备监控、IT 基础设施和应用性能监控以及金融领域的交易数据分析等。在这些场景中，TDengine 能够高效地处理大量的时序数据，为业务决策提供有力支持。

（二）taosAdapter 概述

taosAdapter 是 TDengine 安装包中的一个标准组件，运行在服务器端，进程名 taosAdapter，以服务方式存在，可以通过 systemctl start/stop taosadapter 启动及停止服务 。它在 TDengine 生态系统中充当着 TDengine 集群与应用程序之间的桥梁和适配器角色。

其主要功能包括：

• RESTful 接口支持：支持用户通过 RESTful 接口访问 TDengine 服务，使得应用程序可以使用 HTTP 协议与 TDengine 进行交互。这种方式不依赖 TDengine 客户端驱动，可以跨平台，更加方便灵活，特别适合 Web 应用、移动端应用以及需要与多种不同技术栈集成的场景。例如，前端应用可以通过 RESTful 接口轻松地向 TDengine 写入数据或查询数据，实现数据的实时展示和分析。

• 多种协议兼容：兼容 InfluxDB v1 write 接口、OpenTSDB JSON 和 Telnet 格式写入。这一特性使得原本使用 InfluxDB 或 OpenTSDB 的应用程序能够轻松移植到 TDengine 上，无需进行大量代码修改。企业在进行数据库迁移时，可以利用 taosAdapter 的兼容性，快速将旧系统中的数据接入到 TDengine 中，降低迁移成本和风险。

• 无缝连接数据收集代理工具：能够与各种数据收集代理工具（如 Telegraf、StatsD、collectd 等）无缝对接。这些数据收集代理工具在物联网、运维监控等领域广泛应用，通过与 taosAdapter 连接，可以将收集到的数据直接推送到 TDengine 中进行存储和分析。在一个物联网项目中，部署在各个设备上的 Telegraf 可以实时收集设备的运行状态数据，并通过 taosAdapter 将数据快速写入 TDengine，实现对设备的实时监控和故障预警。

• 支持 WebSocket 连接：除了 RESTful 接口，还支持 WebSocket 连接，为实时性要求较高的应用场景提供了更好的解决方案。WebSocket 允许服务器和客户端之间建立持久的双向通信连接，能够实现数据的实时推送和接收。在实时监控系统中，通过 WebSocket 连接，TDengine 可以将最新的监控数据实时推送给前端页面，用户无需频繁刷新页面即可获取最新信息。

三、RESTful 接口开发原理

（一）RESTful 架构风格

RESTful 是一种软件架构风格、设计风格，而不是标准，由 Roy Thomas Fielding 在 2000 年的博士论文中提出 。它主要用于客户端和服务器交互类的软件，基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。其核心概念和特点如下：

• 资源（Resource）：在 RESTful 架构中，一切皆为资源。资源可以是服务器上的任何信息实体，如文档、图片、数据记录、服务等。每个资源都有一个唯一的标识符，通常使用统一资源标识符（URI）来表示，例如http://example.com/api/users/1就表示了一个 ID 为 1 的用户资源。客户端通过访问 URI 来获取或操作相应的资源。

• 统一接口（Uniform Interface）：RESTful 架构使用统一的接口来访问资源，这些接口基于 HTTP 协议的标准方法，包括 GET、POST、PUT、DELETE、PATCH 等。每个方法都有明确的语义，对应着不同的操作。GET 用于获取资源，GET http://example.com/api/products/可以获取所有产品资源，GET http://example.com/api/products/1则获取 ID 为 1 的产品资源；POST 用于创建新资源，向http://example.com/api/products/发送 POST 请求并携带新产品的数据，即可在服务器上创建一个新的产品；PUT 用于更新资源，将完整的资源数据发送到对应的 URI，如PUT http://example.com/api/products/1并包含更新后的产品数据，服务器会用新数据替换原有数据；DELETE 用于删除资源，DELETE http://example.com/api/products/1可以删除 ID 为 1 的产品资源；PATCH 用于部分更新资源，当只需要更新资源的某些字段时，使用 PATCH 方法发送需要修改的数据，如PATCH http://example.com/api/products/1并携带需要修改的字段数据。这种统一的接口设计使得客户端和服务器之间的交互更加简单和规范，降低了开发和维护的难度。

• 无状态（Stateless）：RESTful 架构要求每个请求都是无状态的，即客户端的每个请求都应包含服务器处理该请求所需的所有信息，服务器不会在请求之间保存客户端的上下文信息。这意味着服务器无需依赖之前的请求来处理当前请求，每个请求都是独立的。在一个电商系统中，客户端请求获取购物车中的商品，请求中应包含用户身份信息等必要参数，服务器根据这些信息处理请求，而不会依赖之前保存的用户购物车状态。无状态的设计使得系统具有更好的可伸缩性和可靠性，因为服务器可以独立地处理每个请求，不需要维护复杂的会话状态，同时也便于缓存和负载均衡。

• 缓存（Cacheable）：为了提高性能，RESTful 架构中的响应应该是可缓存的。客户端可以缓存服务器返回的响应，当再次请求相同的资源时，如果缓存未过期，客户端可以直接使用缓存中的数据，而无需再次向服务器发送请求。这减少了网络流量和服务器负载，提高了系统的响应速度。对于一些不经常变化的资源，如产品列表页面，客户端可以缓存服务器返回的 HTML 或 JSON 数据，下次请求时直接从缓存中读取，而不需要再次从服务器获取。

• 分层系统（Layered System）：RESTful 系统可以被设计为分层的架构，每一层只与相邻的层进行交互。这种分层结构有助于降低系统的复杂性，提高系统的可维护性和可扩展性。在一个典型的 Web 应用中，可能包括客户端层、中间代理层、应用服务器层和数据存储层。客户端与中间代理层交互，中间代理层可以进行缓存、负载均衡等操作，然后与应用服务器层交互，应用服务器层再与数据存储层交互获取或保存数据。每一层都有自己明确的职责，不会了解其他层的内部细节，这样当某一层需要进行修改或替换时，不会影响到其他层。

RESTful 架构风格在接口设计中具有诸多优势。它简化了客户端和服务器之间的交互，使接口更加简洁和易于理解，降低了开发和维护的成本；统一的接口设计使得不同的客户端（如 Web 应用、移动端应用）都能方便地与服务器进行交互，提高了系统的通用性和可移植性；无状态和缓存机制则提高了系统的性能和可伸缩性，能够更好地应对高并发的场景。

（二）TDengine 中 RESTful 接口的实现方式

TDengine 通过 taosAdapter 组件来提供 RESTful 接口，使得应用程序可以使用 HTTP 协议与 TDengine 进行交互。下面详细介绍其接口设计思路和技术实现：

• 接口设计思路：taosAdapter 的 RESTful 接口设计遵循 RESTful 架构的原则，将 TDengine 中的数据和操作抽象为资源，并通过 HTTP 方法进行访问。在 TDengine 中，数据库、表、数据行等都可以看作是资源。一个数据库可以通过/api/v1/databases/{database_name}这样的 URI 来表示，其中{database_name}是具体的数据库名称。通过 GET 方法访问这个 URI 可以获取数据库的相关信息；使用 POST 方法并携带数据库创建的相关参数，可以创建一个新的数据库。对于表资源，/api/v1/databases/{database_name}/tables/{table_name}表示了某个数据库中的一张表，通过不同的 HTTP 方法可以对表进行创建、查询、修改和删除等操作。在数据操作方面，/api/v1/databases/{database_name}/tables/{table_name}/data用于对表中的数据进行操作，POST 方法可以用于插入数据，GET 方法可以用于查询数据。

• 技术实现：taosAdapter 运行在服务器端，作为一个独立的服务进程存在，默认监听 6041 端口 。当客户端发送 HTTP 请求到 taosAdapter 时，taosAdapter 首先解析请求的 URI 和 HTTP 方法，然后根据请求的内容构建相应的 TDengine SQL 语句，并将其发送到 TDengine 服务端进行处理。如果客户端发送一个 GET 请求到/api/v1/databases/mydb/tables/mytable/data?start_time=2023 - 01 - 01&end_time=2023 - 01 - 31，taosAdapter 会解析这个请求，构建出类似SELECT * FROM mydb.mytable WHERE ts BETWEEN '2023 - 01 - 01' AND '2023 - 01 - 31'的 SQL 语句，然后将其发送给 TDengine 服务端执行。TDengine 服务端执行 SQL 语句后返回结果，taosAdapter 再将结果转换为 HTTP 响应的格式（通常为 JSON）返回给客户端。在数据写入方面，如果客户端发送一个 POST 请求到/api/v1/databases/mydb/tables/mytable/data，请求体中包含要插入的数据，taosAdapter 会解析请求体，构建出 INSERT INTO 语句发送给 TDengine 服务端完成数据插入操作。为了保证接口的安全性和稳定性，taosAdapter 还会进行一系列的校验和处理，如身份认证、参数校验、异常处理等。只有通过身份认证的客户端才能访问相应的资源，对于非法的请求参数会返回错误信息给客户端，在处理过程中发生异常时也会进行适当的错误处理并返回给客户端合理的错误提示 。

四、TDengine 与 taosAdapter 结合的优势

（一）便捷的跨平台访问

在当今多元化的技术环境中，不同的应用程序和系统往往运行在各种不同的平台上。通过 taosAdapter 提供的 RESTful 接口，TDengine 实现了便捷的跨平台访问能力，这是其与 taosAdapter 结合的显著优势之一。

由于 RESTful 接口基于 HTTP 协议，而 HTTP 协议是一种广泛支持且平台无关的通信协议，几乎所有的操作系统和编程语言都提供了对 HTTP 的支持 。无论是运行在 Windows、Linux 还是 macOS 系统上的应用程序，都可以轻松地通过 HTTP 请求与 TDengine 进行交互。在一个企业级的物联网项目中，可能存在多种不同类型的设备和系统。其中，一些设备运行在嵌入式 Linux 系统上，负责采集传感器数据；而数据分析和展示部分则运行在 Windows 服务器上，使用 Java 语言开发的 Web 应用进行数据处理和可视化展示。通过 taosAdapter 的 RESTful 接口，运行在嵌入式 Linux 设备上的应用可以方便地将采集到的数据发送到 TDengine 中进行存储，而运行在 Windows 服务器上的 Java Web 应用也能够通过 HTTP 请求从 TDengine 中查询数据，实现数据的实时分析和展示。这种跨平台的访问能力，使得 TDengine 能够轻松地融入各种复杂的技术架构中，与不同平台上的应用程序协同工作，极大地扩展了其应用场景和适用范围。

（二）简化系统集成

在实际的软件开发和系统构建过程中，常常需要将多个不同的系统和组件集成在一起，以实现复杂的业务功能。TDengine 与 taosAdapter 的结合，为系统集成带来了极大的便利，显著简化了集成过程，降低了开发成本。

对于许多已经在使用其他技术栈的项目来说，如果要引入 TDengine 来处理时序数据，往往会面临与现有系统集成的难题。而 taosAdapter 提供的 RESTful 接口以及对多种协议的兼容，使得这一过程变得简单许多。taosAdapter 兼容 InfluxDB v1 write 接口、OpenTSDB JSON 和 Telnet 格式写入。这意味着，如果一个项目原本使用 InfluxDB 或 OpenTSDB 来存储时序数据，现在想要迁移到 TDengine，只需要对数据写入接口进行少量修改，就可以实现数据的无缝迁移。在一个监控系统中，原本使用 InfluxDB 来存储服务器的性能指标数据，如 CPU 使用率、内存占用等。当决定将数据存储迁移到 TDengine 时，由于 taosAdapter 兼容 InfluxDB 的写入接口，开发人员只需要修改数据写入的 URL 和一些参数配置，就可以将原本发送到 InfluxDB 的数据直接写入 TDengine，而无需对整个监控系统的架构进行大规模的重构，大大节省了开发时间和成本。此外，taosAdapter 还能够与各种数据收集代理工具（如 Telegraf、StatsD、collectd 等）无缝对接 。在物联网场景中，这些数据收集代理工具负责从各种设备和传感器中收集数据。通过将这些工具与 taosAdapter 连接，它们可以直接将收集到的数据推送到 TDengine 中进行存储和分析，无需额外的开发工作来实现数据的传输和转换，进一步简化了系统集成的过程。

（三）灵活的数据交互

不同的应用场景对数据交互的方式和需求各不相同，TDengine 与 taosAdapter 的结合，能够实现更加灵活的数据交互，满足多样化的应用需求。

从数据写入方面来看，taosAdapter 支持多种数据格式和协议的写入，开发者可以根据具体的应用场景选择最合适的方式。对于实时性要求较高的物联网设备数据采集场景，可以使用支持高速写入的 InfluxDB v1 write 接口，将设备产生的数据快速写入 TDengine；而对于一些需要兼容旧系统的场景，OpenTSDB JSON 和 Telnet 格式写入则提供了更好的兼容性，使得旧系统中的数据能够顺利迁移到 TDengine 中。在数据查询方面，通过 RESTful 接口，开发者可以使用 HTTP GET 请求来获取数据，并且可以通过在 URL 中添加各种参数来实现灵活的查询条件。在一个能源监测系统中，用户可能需要查询某一时间段内某个地区所有能源设备的平均能耗数据。通过 RESTful 接口，可以发送类似于GET http://example.com/api/v1/databases/energy_db/tables/energy_table/data?start_time=2023 - 01 - 01&end_time=2023 - 01 - 31&group_by=region&aggregate_function=avg&field=energy_consumption的请求，TDengine 会根据这些参数进行数据查询和聚合计算，并返回符合条件的结果。此外，taosAdapter 还支持 WebSocket 连接，这为实时性要求极高的应用场景提供了更强大的数据交互能力。在股票交易实时监控系统中，通过 WebSocket 连接，TDengine 可以将最新的股票交易数据实时推送给前端页面，实现数据的实时更新和展示，用户无需手动刷新页面就能够获取到最新的市场行情信息。