RESTHeart 框架入门指南 | Baeldung中文网

1. 简介

RESTHeart 是一个基于 Java 的框架，能让我们在 MongoDB 之上快速构建 HTTP API。它以最小配置将 MongoDB 集合暴露为 REST 和 GraphQL 接口，同时保留必要的控制能力。

本教程将快速介绍 RESTHeart API 框架的核心功能和使用方法。

2. 什么是 RESTHeart？

RESTHeart 提供了一个构建在 MongoDB 之上的开源 API 服务器。它能自动将集合暴露为 REST 和 GraphQL 接口，让我们无需编写任何代码即可创建 API。

开箱即用的功能包括：

通过 HTTP 和 GraphQL 实现完整的 CRUD 操作
基于角色的访问控制和身份验证
内置管理用户和角色的管理接口
通过 Java 插件或配置实现自定义行为的扩展点

这为构建基于 HTTP 的 API 提供了零代码解决方案，支持快速实现。当需要超出默认功能时，我们还可以集成自定义 Java 代码。

3. 运行 RESTHeart

本地运行 RESTHeart 需要安装 Java 21 或更高版本，并下载 RESTHeart 发行版。下载解压后，直接运行 restheart.jar 即可启动服务：

$ java -jar restheart.jar
17:39:17.943 [main] INFO  org.restheart.Bootstrapper - Starting RESTHeart instance default
17:39:17.945 [main] INFO  org.restheart.Bootstrapper - Version 8.4.0
.....
17:39:19.188 [main] INFO  org.restheart.Bootstrapper - RESTHeart started

无配置时，服务会自动尝试连接 127.0.0.1:27017 上无需凭据的 MongoDB。

也可使用 Docker 镜像运行，并通过 Docker Compose 同时启动 MongoDB。创建 docker-compose.yml 文件：

$ cat docker-compose.yml
services:
  mongodb:
    image: mongo:latest
    container_name: mongodb
    ports:
      - "27017:27017"
    networks:
      - mongo-restheart-network

  restheart:
    image: softinstigate/restheart:latest
    container_name: restheart
    ports:
      - "8080:8080"
    networks:
      - mongo-restheart-network
    environment:
      MONGO_URI: mongodb://mongodb:27017
    depends_on:
      - mongodb

networks:
  mongo-restheart-network:
    driver: bridge

执行 docker compose up -d 启动服务：

$ docker compose up -d
[+] Running 3/3
   Network restheart_mongo-restheart-network  Created
   Container mongodb                          Started
   Container restheart                        Started

启动后，调用 /ping 接口验证服务状态：

$ curl localhost:8080/ping
{"message": "Greetings from RESTHeart!", "client_ip": "192.168.65.1", "host": "localhost:8080", "version": "8.4.0"}

至此，一个完整可用的服务已就绪。

4. 身份验证与用户管理

RESTHeart 自动处理大部分 API 调用的身份验证。例如，未认证访问根资源会返回 HTTP 401 Unauthorized：

$ curl -v localhost:8080/
> GET / HTTP/1.1
>
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Basic realm="RESTHeart Realm"

默认情况下，用户记录存储在 MongoDB 的 users 集合中。空数据库启动时，该集合会自动创建并添加一个 admin 用户：

默认凭据为用户名 admin 和密码 secret（密码已安全哈希）。使用这些凭据重新请求：

$ curl -v -u admin:secret localhost:8080/
> GET / HTTP/1.1
> Authorization: Basic YWRtaW46c2VjcmV0
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
["acl", "users"]

✅ 请求成功，返回预期响应。

5. 使用 RESTHeart 进行 CRUD 操作

RESTHeart 自动暴露 MongoDB 集合，通过标准 REST 和 GraphQL 接口实现数据读写。

5.1 REST API

RESTHeart 为每个集合提供标准 URL 模式的 REST 接口：

GET / – 查询集合
GET // – 获取单条记录
POST / – 创建新记录
PUT // – 替换记录
PATCH // – 部分更新记录
DELETE // – 删除记录

通过特殊请求创建新集合：向集合接口发送 PUT 请求：

$ curl -v -u admin:secret -X PUT localhost:8080/posts
> PUT /posts HTTP/1.1
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 0
<

使用 POST 请求创建新记录：

$ curl -v -u admin:secret -X POST localhost:8080/posts -d '{"title": "Introduction to RESTHeart", "author": "Baeldung"}' -H "Content-Type: application/json"
> POST /posts HTTP/1.1
> Content-Type: application/json
> Content-Length: 60
>
< HTTP/1.1 201 Created
< Location: http://localhost:8080/posts/681a139012d5c00fcb674298

响应不返回记录内容，但通过 Location 头提供访问地址。数据库中直接可见：

通过 GET 请求和 ID 检索记录：

$ curl -v -u admin:secret localhost:8080/posts/681a139012d5c00fcb674298
> GET /posts/681a139012d5c00fcb674298 HTTP/1.1
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 152
<
{
  "_id": { "$oid": "681a139012d5c00fcb674298" },
  "title": "Introduction to RESTHeart",
  "author": "Baeldung",
  "_etag": { "$oid": "681a139012d5c00fcb674297" }
}

对整个集合使用 GET 请求获取所有记录：

$ curl -v -u admin:secret localhost:8080/posts
> GET /posts HTTP/1.1
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 154
<
[
  {
    "_id": { "$oid": "681a139012d5c00fcb674298" },
    "title": "Introduction to RESTHeart",
    "author": "Baeldung",
    "_etag": { "$oid": "681a139012d5c00fcb674297" }
  }
]

通过 PUT、PATCH 和 DELETE 更新或删除记录：

$ curl -v -u admin:secret -X PUT localhost:8080/posts/681a139012d5c00fcb674298 -H "Content-Type: application/json" -d '{"title": "Intro to RESTHeart", "author": "Baeldung"}'
> PUT /posts/681a139012d5c00fcb674298 HTTP/1.1
> Content-Type: application/json
> Content-Length: 53
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 0
<

⚠️ 这些操作不返回结果，但再次查询即可验证更新。

5.2 GraphQL API

RESTHeart 还支持通过 GraphQL API 暴露数据。与 REST API 不同，GraphQL 需要初始配置。

所有 GraphQL API 由 gql-apps 集合中的记录定义。首先创建该集合：

$ curl -v -u admin:secret -X PUT localhost:8080/gql-apps

然后创建包含 API 定义的特殊记录。以下配置暴露之前使用的 posts 集合：

$ cat posts.schema
{
    "_id": "restheart-posts",
    "descriptor": {
        "name": "restheart-posts",
        "description": "RESTHeart Tutorial",
        "enabled": true,
        "uri": "restheart-posts"
    },
    "schema": "type Post { title: String author: String } type Query { posts: [Post] }",
    "mappings": {
        "Post": {
            "name": "name",
            "author": "author"
        },
        "Query": {
            "posts": {
                "db": "restheart",
                "collection": "posts"
            }
        }
    }
}

descriptor 字段定义 API 管理参数，关键参数是 uri（用于访问路径）。schema 字段是用 GraphQL Schema Definition Language 编写的完整 Schema 定义。mappings 字段描述 GraphQL 与 MongoDB 集合的映射关系。

创建记录：

$ curl -v -u admin:secret -X POST localhost:8080/gql-apps -d "@posts.schema" -H "Content-Type: application/json"

GraphQL API 已就绪。uri 设置为 restheart-posts，因此接口位于 /graphql/restheart-posts：

$ curl -v -u admin:secret -X POST localhost:8080/graphql/restheart-posts -d "{ posts { title author } }" -H "Content-Type: application/graphql"
> POST /graphql/restheart-posts HTTP/1.1
> Content-Type: application/graphql
> Content-Length: 26
>
* upload completely sent off: 26 bytes
< HTTP/1.1 200 OK
< Content-Type: application/graphql-response+json
< Content-Length: 83
<
{
  "data": {
    "posts": [
      {
        "title": "Intro to RESTHeart",
        "author": "Baeldung"
      }
    ]
  }
}

✅ 返回数据与 REST API 管理的数据一致。

6. 总结

本文简要介绍了 RESTHeart 及其核心功能。该框架还有更多高级特性等待探索。下次需要创建 HTTP API 时，不妨试试这个简单粗暴的解决方案。

Persistence

REST

Security