Public API for Annotations (public-annotations-api)

概述

为存储在Neo4J图数据库中的注释提供公共API访问服务。

核心功能与特性

• 提供HTTP接口获取指定内容UUID的注释数据
• 支持从Neo4J图数据库查询和返回注释信息
• 可配置缓存时长，默认缓存1小时
• 支持日志级别设置（DEBUG/INFO/WARN/ERROR）
• 包含健康检查、构建信息等管理端点

安装与本地运行

环境准备

1. 安装依赖管理工具：
   curl [***] | sh

2. 获取源码：
   go get -u github.com/Financial-Times/public-annotations-api

3. 进入项目目录：
   cd $GOPATH/src/github.com/Financial-Times/public-annotations-api

4. 安装依赖包：
   dep ensure -vendor-only

5. 编译项目：
   go install

启动服务

$GOPATH/bin/public-annotations-api --neo-url={neo4jUrl} --port={port} --log-level={DEBUG|INFO|WARN|ERROR} --cache-duration={e.g. 22h10m3s}

参数说明

• --neo-url：Neo4J数据库URL，默认值为http://localhost:7474/db/data（本地Neo4J默认地址）
• --port：服务端口，默认值为8080
• --log-level：日志级别，可选值为DEBUG、INFO、WARN、ERROR
• --cache-duration：缓存时长，默认值为1h（格式示例：22h10m3s）

验证服务

• 使用curl验证：
  curl http://localhost:8080/content/143ba45c-2fb3-35bc-b227-a6ed80b5c517/annotations | json_pp

• 或使用httpie：
  http GET http://localhost:8080/content/143ba45c-2fb3-35bc-b227-a6ed80b5c517/annotations

测试

单元测试

go test -race ./...

集成测试

docker-compose -f docker-compose-tests.yml up -d --build && \
docker logs -f test-runner && \
docker-compose -f docker-compose-tests.yml down

构建与部署

• 持续构建：通过CircleCI进行持续构建
• 镜像构建：Dockerhub基于git发布标签自动构建镜像
• 发布流程：在GitHub仓库页面创建新发布标签触发构建
• 集群部署：public-annotations-api
• CI服务：CircleCI
• 代码覆盖率：Coveralls

API定义

基于Google文档规范实现。

GET /content/{uuid}/annotations 端点

返回指定内容UUID的所有注释数据（JSON格式）。

响应特性

• 品牌层级包含：返回品牌注释及其所有父品牌（递归包含上级父品牌）
• 生命周期过滤：
  • 若存在已审核（pac生命周期）注释，默认返回其与V2注释的组合，忽略其他生命周期注释
  • 若无pac注释，则返回非pac注释
  • 可通过lifecycle查询参数进一步过滤
• 关系优先级过滤：同一概念存在多个注释关系时，仅返回优先级最高的关系：
  • 例如：同时存在"About"、"Major Mentions"和"Mentions"关系时，仅返回"About"
  • 例如：同时存在"Is Classified By"和"Is Primarily Classified By"时，仅返回"Is Primarily Classified By"

管理端点

• 健康检查：http://localhost:8080/__health
• 构建信息：http://localhost:8080/__build-info
• 服务就绪检查：http://localhost:8080/__gtg

日志

使用logrus日志库，日志配置在main.go中初始化。

• 输出位置：
  • 非本地环境：日志写入文件
  • 本地环境：日志输出到控制台（如需本地写入文件，需传入非"local"的环境参数）
• 特殊说明：/__gtg端点不记录日志（因每秒被varnish调用，无需记录冗余信息到日志/Splunk）