Consul 注册发现 API

Consul 的全部能力都暴露为 HTTP API，注册、查询、注销、心跳走同一套 REST 接口，默认监听 8500 端口、返回 JSON，是各语言 SDK 的底层协议。

注册服务

向本机 agent 提交服务定义，PUT /v1/agent/service/register，body 为 JSON：

curl -X PUT http://127.0.0.1:8500/v1/agent/service/register -d '{
  "id": "order-1",
  "name": "order",
  "address": "192.168.1.20",
  "port": 9001,
  "tags": ["v1"],
  "check": { "tcp": "192.168.1.20:9001", "interval": "10s" }
}'
# 返回 200 与空 body 即注册成功

查询服务

查询分两类接口：catalog 返回目录原始数据，health 带健康过滤，实际调用多用 health：

# 目录查询：返回该服务全部实例（含不健康）
curl http://127.0.0.1:8500/v1/catalog/service/order
# 健康查询：?passing=true 只返回健康实例
curl "http://127.0.0.1:8500/v1/health/service/order?passing=true"

health 返回的数组元素主要字段：

字段	含义
Service.ID / Service.Name	实例 ID 与服务名
Service.Address / Service.Port	实例地址与端口
Service.Tags	注册时的标签
Checks[].Status	每个检查的状态：passing / critical / warning

注销服务

不再需要实例时按服务 ID 注销：

curl -X PUT http://127.0.0.1:8500/v1/agent/service/deregister/order-1
# 返回 200 即注销成功
curl "http://127.0.0.1:8500/v1/health/service/order?passing=true"
# 返回 []，说明已无健康实例

TTL 检查与心跳

不适合被动探测的业务（定时任务、后台 worker）用 TTL 检查：注册时只声明 ttl 过期时长，由业务自己周期上报心跳，超时未报 agent 即判 critical：

curl -X PUT http://127.0.0.1:8500/v1/agent/service/register -d '{
  "name": "worker",
  "check": { "ttl": "30s" }
}'
# 业务每 15 秒上报一次心跳（该检查 ID 默认为 service:worker）：
curl -X PUT http://127.0.0.1:8500/v1/agent/check/pass/service:worker
# 主动上报失败/告警用 warn、fail 结尾的接口

curl 完整演示流程

起一个 dev agent，即可跑通"注册→查询→心跳→注销"闭环：

# 1 注册 demo 服务
curl -X PUT http://127.0.0.1:8500/v1/agent/service/register -d '{"name":"demo","port":1}'
# 2 查询健康实例，能看到 demo
curl "http://127.0.0.1:8500/v1/health/service/demo?passing=true"
# 3 注销 demo
curl -X PUT http://127.0.0.1:8500/v1/agent/service/deregister/demo
# 4 再查为空
curl "http://127.0.0.1:8500/v1/health/service/demo?passing=true"
# 返回 []

小结

注册、查询、注销、心跳四类接口覆盖动态服务管理主流程：register 登记、health/catalog 查询、deregister 摘除、check/pass 续命。程序接入优先用官方 SDK，它封装的正是这套 API。