annotations-rw-neo4j 镜像文档

镜像概述和主要用途

annotations-rw-neo4j是一个用于在Neo4j中读写注释的服务和API。它支持从消息队列消费消息并写入Neo4j，若同时启用生产者，消息会被转发到下一个（PostAnnotations）队列。此外，该流程也可通过PUT端点触发，此时服务期望接收注释消费者输出格式的JSON数据。

核心功能和特性

• 注释读写管理：提供API接口实现Neo4j中注释的创建、查询和删除操作
• 消息队列集成：支持从队列消费消息写入Neo4j，并可转发消息到后续队列
• PUT端点触发：通过HTTP PUT请求直接触发注释写入流程，支持批量处理
• 原子性操作：PUT请求会替换指定生命周期的所有注释，空列表则删除全部注释
• 错误处理：提供明确的HTTP响应码（201成功、400无效请求、500服务器错误）
• 健康检查：内置健康状态检查和心跳检测接口

使用场景和适用范围

• 需要管理Neo4j数据库中注释数据的微服务架构
• 需通过消息队列异步处理注释数据的业务场景
• 需要批量操作注释并保证数据一致性的应用
• 需监控服务健康状态的生产环境部署

详细使用方法和配置说明

环境变量配置

Docker运行示例

# 基本运行配置（连接本地Neo4j和Kafka）
docker run -d \
  -p 8080:8080 \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e KAFKA_BROKERS=kafka:9092 \
  -e SHOULD_FORWARD_MESSAGES=true \
  --name annotations-rw-neo4j \
  annotations-rw-neo4j:latest

# 禁用消息转发（仅本地测试用）
docker run -d \
  -p 8080:8080 \
  -e NEO4J_URI=bolt://localhost:7687 \
  -e SHOULD_FORWARD_MESSAGES=false \
  --name annotations-rw-neo4j-local \
  annotations-rw-neo4j:latest

API端点说明

PUT /content/{annotatedContentId}/annotations/{annotations-lifecycle}

功能：替换指定内容ID和生命周期的注释，空列表将删除所有注释

请求参数：

• annotatedContentId：被注释内容的ID
• annotations-lifecycle：注释生命周期标识

请求体：注释JSON数组（示例格式如下）

[
  {
    "id": "[***]",
    "predicate": "MENTIONS",
    "provenances": [
      {
        "agent": "annotator-service",
        "score": 0.95,
        "time": "2024-01-01T00:00:00Z"
      }
    ]
  }
]

响应说明：

• 201：注释成功写入
• 400：请求体JSON格式无效
• 500：批量处理失败

使用示例：

curl -XPUT -H "X-Request-Id: 123" -H "Content-Type: application/json" \
  http://localhost:8080/content/3fa70485-3a57-3b9b-9449-774b001cd965/annotations/annotations-v1 \
  --data @annotations.json

GET /content/{annotatedContentId}/annotations/{annotations-lifecycle}

功能：查询指定内容ID和生命周期的注释（内部API，非公共注释查询接口）

响应：

• 200：返回注释JSON数组
• 404：未找到对应注释

使用示例：

curl -H "X-Request-Id: 123" \
  http://localhost:8080/content/3fa70485-3a57-3b9b-9449-774b001cd965/annotations/annotations-v1

DELETE /content/{contentId}/annotations/{annotations-lifecycle}

功能：删除指定内容ID和生命周期的所有注释

响应：

• 204：删除成功
• 404：未找到对应注释

使用示例：

curl -XDELETE -H "X-Request-Id: 123" \
  http://localhost:8080/content/3fa70485-3a57-3b9b-9449-774b001cd965/annotations/annotations-v1

健康检查

• 健康状态检查：http://localhost:8080/__health
• 心跳检测：http://localhost:8080/__ping

注意事项

• 注释本身无标识符，JSON中的id字段为注释关联的概念ID
• PUT操作具有原子性，失败时返回500错误，需重试整个批量操作
• 禁用Kafka功能时，设置SHOULD_FORWARD_MESSAGES=false
• 本地测试建议使用Docker运行Neo4j和Kafka以简化环境配置