OGC API Records 服务文档

1. 概述与主要用途

OGC API Records 是一个基于 OGC API Records 标准实现的服务，用于提供记录集合的标准化 API 访问。该服务允许客户端查询记录集合、检索单个记录、执行高级搜索（包括全文搜索、空间搜索等），并支持多种输出格式和多语言响应，适用于地理信息元数据管理、数据目录服务等场景。

2. 核心功能与特性

2.1 数据访问能力

• 集合管理：查询所有可用集合、获取单个集合详情（支持 OpenSearch 描述文档输出）
• 记录操作：检索集合中的记录列表、获取单个记录详情
• 高级搜索：
  • 全文搜索（通过 q 参数）
  • 空间范围搜索（通过 bbox 参数，支持空间相交关系）
  • 记录 ID 筛选（通过 externalids 参数）
  • 分页控制（通过 limit 和 startindex 参数）

2.2 输出格式支持

• 结构化数据：JSON、XML、application/ld+json、application/dcat2+xml
• 文档格式：HTML（支持多语言）
• Feed 格式：application/rss+xml
• 语义网格式：text/turtle、application/rdf+xml
• 可通过 f URL 参数显式指定格式（如 ?f=xml）

2.3 多语言支持

通过 Accept-Language 请求头或 l URL 参数指定响应语言（如 Accept-Language: fr 或 ?l=fr）。

2.4 部署灵活性

• 支持独立 JAR 包部署（standalone 模式）
• 支持 WAR 包部署（可集成到 Servlet 容器如 Jetty）
• 支持自定义配置文件和 Spring Profiles

3. 使用场景与适用范围

• 地理信息目录服务：为地理空间元数据提供标准化 API 访问接口
• 元数据管理系统：集成到现有元数据平台，提供外部系统访问能力
• 多系统数据集成：支持多种输出格式，便于不同系统（如 GIS 工具、数据门户）对接
• 多语言数据服务：面向国际化用户群体，提供多语言响应

4. 使用方法与配置说明

4.1 环境准备

• JDK 8+
• Maven 3.6+

4.2 构建服务

shell
# 编译并生成 OpenAPI 代码
mvn clean compile

生成的代码位于 target/generate-sources 目录。

4.3 启动服务

4.3.1 开发环境启动

shell
# 默认启动（使用默认端口和配置）
mvn spring-boot:run

# 自定义端口和 Profile
SERVER_PORT=9901 mvn spring-boot:run -Dspring-boot.run.profiles=standalone

4.3.2 热更新 XSLT 文件

运行中更新 XSLT 资源文件：

shell
mvn process-resources

# 若需更新其他模块共享的 XSLT（如 common-view 模块），可通过以下方式：
# cd modules/library/common-view; mvn compile
# 或创建符号链接（示例）：
# cd modules/services/ogc-api-records/service/src/main/resources/xslt
# ln -s ../../../../../../../library/common-view/src/main/resources/xslt/core core

4.4 独立服务部署（JAR 模式）

4.4.1 构建 JAR 包

shell
mvn package

4.4.2 启动 JAR 包

shell
# 基础启动（指定端口和 standalone Profile）
SERVER_PORT=9901 java -Dspring.profiles.active=standalone -jar target/gn-ogc-api-records.jar

# 自定义配置文件位置
SERVER_PORT=9901 java -Dspring.profiles.active=standalone -Dspring.config.location=./config/ -jar target/gn-ogc-api-records.jar

4.5 WAR 包部署

4.5.1 构建 WAR 包

shell
cd modules/services/ogc-api-records/service
mvn package -Pwar,-docker

4.5.2 运行 WAR 包（Jetty 示例）

shell
mvn jetty:run -Pwar -Dspring.profiles.active=standalone -Dspring.config.location=./service/src/main/resources/

4.6 配置参数

4.6.1 环境变量

4.6.2 Spring 配置

• Profiles：通过 -Dspring.profiles.active=standalone 指定，支持多环境配置
• 配置文件位置：通过 -Dspring.config.location=./config/ 指定外部配置目录（优先级高于内置配置）

4.6.3 URL 请求参数

5. 服务测试

5.1 集合查询

5.1.1 获取所有集合（JSON 格式）

shell
curl 127.0.0.1:9901/collections \
  -H "Accept: application/json"

5.1.2 获取所有集合（HTML 格式，法语）

shell
# 通过 Accept-Language 头
curl 127.0.0.1:9901/collections \
  -H "Accept: text/html" -H "Accept-Language: fr"

# 通过 l 参数
curl 127.0.0.1:9901/collections?l=fr \
  -H "Accept: text/html"

5.2 单个集合操作

5.2.1 获取首个集合详情（JSON 格式）

shell
# 提取首个集合名称
firstCollection=$( \
  curl 127.0.0.1:9901/collections \
    -H "Accept: application/json" \
    | jq -r '.collections[0].name' \
)

# 查询集合详情
curl 127.0.0.1:9901/collections/$firstCollection \
  -H "Accept: application/json"

5.2.2 获取集合的 OpenSearch 描述文档

shell
curl 127.0.0.1:9901/collections/$firstCollection \
  -H "Accept: application/opensearchdescription+xml"

5.2.3 获取集合可排序字段

shell
curl 127.0.0.1:9901/collections/$firstCollection/sortables \
  -H "Accept: application/json"

5.3 记录查询与搜索

5.3.1 获取记录列表（多格式）

shell
# JSON 格式
curl 127.0.0.1:9901/collections/$firstCollection/items \
  -H "Accept: application/json"

# XML 格式
curl 127.0.0.1:9901/collections/$firstCollection/items \
  -H "Accept: application/xml"

# RSS 格式
curl 127.0.0.1:9901/collections/$firstCollection/items \
  -H "Accept: application/rss+xml"

5.3.2 分页查询

shell
# 限制每页 20 条记录
curl 127.0.0.1:9901/collections/$firstCollection/items?limit=20 \
  -H "Accept: application/json"

# 从第 20 条开始，每页 20 条（第二页）
curl 127.0.0.1:9901/collections/$firstCollection/items?startindex=20&limit=20 \
  -H "Accept: application/json"

5.3.3 全文搜索

shell
curl 127.0.0.1:9901/collections/$firstCollection/items?q=map \
  -H "Accept: application/json"

5.3.4 空间范围搜索

shell
# bbox 参数格式：minx,miny,maxx,maxy（空间相交关系）
curl 127.0.0.1:9901/collections/$firstCollection/items?bbox=-100,40,-80,50 \
  -H "Accept: application/json"

5.3.5 按 ID 筛选记录

shell
curl 127.0.0.1:9901/collections/$firstCollection/items?externalids=8306437bc59910b70223865b44100ffab97ba069&externalids=8a9bc9e8f86cb02be8be4450e310d261415ac909 \
  -H "Accept: application/json"

5.4 单个记录查询

5.4.1 获取首个记录 ID 并查询详情（多格式）

shell
# 提取首个记录 ID
uuid=$( \
  curl 127.0.0.1:9901/collections/$firstCollection/items \
    -H "Accept: application/json" \
    | jq -r '.hits.hits[0]._id' \
)

# JSON 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: application/json"

# JSON-LD 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: application/ld+json"

# XML 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: application/xml"

# DCAT2 XML 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: application/dcat2+xml"

# Turtle 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: text/turtle"

# RDF XML 格式
curl 127.0.0.1:9901/collections/$firstCollection/items/$uuid \
  -H "Accept: application/rdf+xml"

6. Docker 部署方案

6.1 Docker Run 命令

shell
# 构建 JAR 包（需本地预先构建）
mvn package

# 启动容器（standalone 模式，暴露 9901 端口，挂载配置目录）
docker run -d \
  --name ogc-api-records \
  -p 9901:9901 \
  -e SERVER_PORT=9901 \
  -e SPRING_PROFILES_ACTIVE=standalone \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/target/gn-ogc-api-records.jar:/app/gn-ogc-api-records.jar \
  openjdk:11-jre-slim \
  java -jar /app/gn-ogc-api-records.jar

6.2 Docker Compose 配置

创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  ogc-api-records:
    image: openjdk:11-jre-slim
    container_name: ogc-api-records
    restart: always
    ports:
      - "9901:9901"
    environment:
      - SERVER_PORT=9901
      - SPRING_PROFILES_ACTIVE=standalone
      - SPRING_CONFIG_LOCATION=file:/app/config/
    volumes:
      - ./config:/app/config  # 外部配置目录（可选）
      - ./target/gn-ogc-api-records.jar:/app/gn-ogc-api-records.jar
    command: java -jar /app/gn-ogc-api-records.jar

启动服务：

shell
docker-compose up -d

7. 源代码

GitHub 仓库