API on Liangweidong's blog

REST API 企业级设计实战：登录鉴权、重大危险源、双预防与园区版双向同步

Sun, 15 Nov 2020 00:00:00 +0800

背景：本文以一份 1931 行的"安全生产类平台"接口规范为蓝本——它包含登录、重大危险源监测设备、双预防（安全风险分析单元/事件/管控措施/隐患排查任务/记录/信息）、特殊作业票、教育培训等 30+ 个端点，全部采用统一响应体 + Bearer Token + add/update/delete 三段式风格。本文重点不是"再写一遍规范"，而是抽丝剥茧出企业级 REST API 设计的 6 大原则，让读者下次写接口时直接对号入座。

Why 2020 年：REST 在 2014-2018 完成主流化（Spring 5 / JAX-RS 2.1 / OpenAPI 3.0 都是这一时期定型的），2020 年是企业从"能跑"转向"规范 + 可观测"的分水岭。本文的方法论至今仍是企业级接口设计的底座。

一、统一响应体：把"成功"和"业务失败"分开

很多团队在写 REST 接口时，第一反应是"成功返回数据、失败抛 4xx/5xx + 异常 message"——但企业级 API 必须把"协议层错误"和"业务层错误"分开，否则前端要写两套解析逻辑，后端监控也要维护两套指标。

1.1 业界三大响应体风格对比

风格	成功	业务失败	网络失败	典型代表
HTTP 优先	`200 + 数据`	`4xx/5xx + 错误体`	`5xx + 异常`	Spring MVC 默认、Express 默认
统一信封	`200 + {code:0, data}`	`200 + {code:1xxx, msg}`	`5xx + 异常`	阿里云 API、字节内部 RPC 协议
混合模式	`200/201 + 数据`	`4xx + 业务 code`	`5xx + 异常`	GitHub API、Stripe API

这份规范采用"统一信封"风格，所有业务成功都返回 200，靠 code 字段区分：

1
2
3
4
5
6


{
 "msg": "成功",
 "code": 0,
 "data": null,
 "success": true
}

设计要点：

code = 0 表示业务成功，非 0 表示业务错误（避免误用 HTTP 200 + 业务失败 + HTTP 4xx 三者交叉）

success 冗余但友好，前端 if (res.success) 比 if (res.code === 0) 可读性高

msg 用中文（业务系统），对外公开的 API 建议英文 + 国际化 key

data 类型根据业务而定，列表/对象/null 都允许

1.2 状态码语义对照表

HTTP 状态码	业务场景	后端处理	前端处理
200	业务成功（包含 `code != 0` 业务失败）	永远返回 200	看 `success` 字段
400	请求参数格式错误（JSON 解析失败）	Spring `@Valid` 触发	弹"参数错误"Toast
401	Token 缺失/过期/无效	拦截器抛 `AuthException`	跳登录页
403	权限不足	RBAC 拦截	弹"无权限"
404	资源不存在	`@ExceptionHandler`	弹"记录不存在"
429	限流	Sentinel/Sentinel 拦截	弹"操作太频繁"
500	系统异常	全局异常处理	弹"系统异常"+ 上报埋点
502/503/504	网关/上游异常	Nginx/OpenResty	弹"服务暂不可用"

二、URL 命名：模块化 + 资源化 + 动词三段式

这份规范的 URL 设计非常典型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


POST /hazard/monitorEquip/add # 重大危险源-监测设备-新增
POST /hazard/monitorEquip/update # 重大危险源-监测设备-修改
POST /hazard/monitorEquip/delete # 重大危险源-监测设备-删除
POST /prevent/riskUnit/add # 双预防-风险分析单元-新增
POST /prevent/riskEvents/add # 双预防-安全风险事件-新增
POST /prevent/riskMeasures/add # 双预防-管控措施-新增
POST /prevent/troubleshootTask/add # 双预防-隐患排查任务-新增
POST /prevent/troubleshootRecord/add # 双预防-隐患排查记录-新增
POST /prevent/troubleshootInfo/add # 双预防-隐患排查信息-新增
POST /prevent/ticketBaseInfo/add # 特殊作业票-票证信息-新增
POST /prevent/trainBaseInfo/add # 教育培训-培训信息-新增

2.1 URL 设计的 4 层语义

层级	含义	这份规范的做法
L1 一级模块	业务域	`hazard`（重大危险源）、`prevent`（双预防 + 特殊作业票 + 教育培训）、`system`（系统）
L2 二级模块	子系统	`monitorEquip`（监测设备）、`riskUnit`（风险单元）
L3 动作	CRUD	`add` / `update` / `delete`（不是 RESTful 的 POST/GET/PUT/DELETE）
L4 路径参数	资源 ID	写在请求体 `id` 字段，不是 URL

2.2 这种"动作式 URL" vs RESTful 风格

RESTful 风格（HTTP 动词 + 资源）：

1
2
3
4


POST /api/v1/hazard/monitor-equip # 新增
GET /api/v1/hazard/monitor-equip/{id} # 查询
PUT /api/v1/hazard/monitor-equip/{id} # 修改
DELETE /api/v1/hazard/monitor-equip/{id} # 删除

这份规范的动作式风格：

1
2
3


POST /hazard/monitorEquip/add
POST /hazard/monitorEquip/update
POST /hazard/monitorEquip/delete

维度	RESTful	动作式（这份规范）
HTTP 动词丰富度	4-5 个	仅 POST（与 CSRF/中间件兼容性好）
网关路由匹配	复杂（要看动词）	简单（只看路径）
审计日志	看 `method + path`	看 `path`（更易聚合）
团队学习成本	中	低（无歧义）
幂等性	需显式声明	`update`/`delete` 天然要求幂等
OpenAPI 自动生成	友好	不友好（同一路径下多个动作）

我的建议：对内系统、CRUD 密集型、强审计 → 动作式（add/update/delete）；对外 API、平台化 → RESTful。这份规范属于前者，理由是它要对接大量前端 + 移动端 + 第三方园区版系统，用 POST /xxx/add 这种风格，后端可以用统一的请求体 + 鉴权 + 日志拦截器，避免 HTTP 动词带来的中间件兼容性问题。

2.3 命名规范：驼峰 vs 短横线

1
2
3
4
5
6
7


# 驼峰（这份规范）
/hazard/monitorEquip
/prevent/riskUnit

# 短横线（RESTful 推荐）
/hazard/monitor-equip
/prevent/risk-unit

风格	优点	缺点
驼峰 `monitorEquip`	与 Java/Go 字段名一致	URL 编码 `%2D` 不需要，但 RFC 3986 不推荐
短横线 `monitor-equip`	RFC 3986 友好、SEO 友好	需与字段名手动映射

最佳实践：对外 API 用短横线（GitHub、Twitter、Stripe 都这样），对内 RPC 用驼峰（与业务代码一致，减少转换）。

三、鉴权：Bearer Token + 30 天有效期

3.1 登录接口

1
2


POST /system/login
Content-Type: application/json

请求体：

1
2
3
4


{
 "userName": "{{USERNAME}}",
 "password": "{{PASSWORD}}"
}

响应体：

1
2
3
4
5
6
7
8


{
 "msg": "",
 "code": 0,
 "data": {
 "token": "{{TOKEN}}"
 },
 "success": true
}

脱敏说明：源文档中 userName 默认填 admin、password 默认填 123456、token 是一个真实的 UUID 格式字符串（b5b6b03f-18f4-4caf-acdf-25c5cc555bd3）。默认账号密码不应在博文中演示，token 也应视为凭据——博文全部用 {{}} 占位。

3.2 业务请求的鉴权头

1
2
3


POST /hazard/monitorEquip/add
Authorization: Bearer {{TOKEN}}
Content-Type: application/json

关键设计：

项	取值	原因
鉴权方案	`Bearer Token`	RFC 6750 标准，与 OAuth 2.0 / OIDC 兼容
有效期	30 天	长效适合企业用户（避免每天重新登录），但配合刷新机制更佳
存储	localStorage / sessionStorage	前端选型决定（localStorage 持久但有 XSS 风险，HttpOnly Cookie 安全但要 CSRF 防护）
传输	HTTPS 强制	防止 token 泄露
撤销	服务端黑名单 + JWT	推荐：Redis 黑名单 + 短 JWT

3.3 进阶：刷新令牌模式

1
2


POST /system/refresh
Authorization: Bearer {{REFRESH_TOKEN}}

返回新的 access_token（短效 2 小时）+ 复用 refresh_token（长效 30 天）。这种"双 token"模式是 OAuth 2.0 推荐的工业实践，避免一个长效 token 泄露就要全员重置。

四、请求/响应体设计：5 个核心要素

4.1 请求体的 5 段式结构

以"重大危险源-监测设备-新增"为例（这份规范最详细的端点）：

要素	字段	类型	必选	备注
基础标识	`id`	string	是	主键
业务字段	`monitorName` `monitorCode` `monitorType` `numericalUnit` `rangeMax` `rangeMin`	string	是	业务核心数据
责任字段	`responsibilityPeopleName` `deptName`	string	是	责任人/部门
位置字段	`longitude` `latitude` `address`	number/string	是	经纬度 + 地址
设备字段	`manufacturer` `checkTime` `checkCycle`	string/datetime	是	厂家/校验
告警字段	`oneLevelHigh` `twoLevelHigh` `oneLevelLow` `twoLevelLow`	string	是	一二级高低报
类型字段	`monitorSpotType` `state` `equipmentType` `equipmentName`	string	是	类型/状态

4.2 字段类型选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


字段值是什么？
├── 中文/枚举/编号
│ ├── 固定有限集合 → string（"男"/"女"、"已处理"/"未处理"）
│ ├── 不定文本 → string（地址、姓名、备注）
│ └── 编号/UUID → string（不直接用 number！避免 JS 精度问题）
│
├── 数值
│ ├── 整数计数 → int（年龄、数量）
│ ├── 小数金额 → string 或 long（避免精度问题，"1.23"）
│ ├── 经纬度 → number（前端 leaflet/高德直接用）
│ └── 大 ID → string（雪花 ID 19 位超出 JS Number 安全范围）
│
└── 时间
 ├── 精确到秒 → string ISO 8601（"2026-06-04T10:30:00+08:00"）
 ├── 仅日期 → string（"2026-06-04"）
 └── 时间戳 → long（毫秒，前端 new Date(ms)）

关键提醒：永远不要用 number 表示 ID/编号/金额！JavaScript 的 Number 是双精度浮点，Number.MAX_SAFE_INTEGER 是 9007199254740991（约 9 * 10^15），超出后 12345678901234567 === 12345678901234568 会返回 true。雪花 ID 通常是 18-19 位，必须用 string。

4.3 必选/可选字段的标注规范

1
2
3
4
5


# 推荐：仅标注"必选"（默认是可选）
"id": { "type": "string", "required": true, "desc": "主键" }
"monitorName": { "type": "string", "required": true, "desc": "监测点名称" }

# 不推荐：每个字段都标注 required: false（噪音）

4.4 错误响应体的差异化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 业务错误（4xx + 业务 code）
{
 "msg": "监测点编号已存在",
 "code": 1001,
 "data": null,
 "success": false
}

// 系统错误（5xx + 异常 trace）
{
 "msg": "系统繁忙，请稍后重试",
 "code": -1,
 "data": null,
 "success": false
}

code 设计原则：

0 = 成功

1xxx = 业务错误（参数错误、唯一冲突、状态非法等）

2xxx = 鉴权错误（token 过期、权限不足）

3xxx = 第三方错误（短信/邮件/支付失败）

4xxx-5xxx = 内部错误（数据库异常、Redis 异常等）

-1 = 系统兜底

五、批量与同步：园区版双向同步的 4 种模式

这份规范有一个特殊设计：几乎所有端点的接口功能都写"企业版新增数据时同步到园区版"——这意味着每个写操作都是双写的。这种"企业版 + 园区版"的同步模式在政企/工业互联网场景非常典型。

5.1 4 种同步模式对比

模式	实时性	复杂度	一致性	适用
同步双写	实时	低	强	企业版 ↔ 园区版（这份规范的做法）
异步消息	准实时（秒级）	中	最终一致	跨地域多活、削峰填谷
CDC 监听	准实时	高	最终一致	数据库迁移、异构同步
定时拉取	延迟（分钟/小时）	低	弱	对账、非关键数据

5.2 同步双写的实现细节

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


@PostMapping("/hazard/monitorEquip/add")
public Result<?> addMonitorEquip(@RequestBody MonitorEquipDTO dto) {
 // 1. 参数校验
 validator.validate(dto);
 
 // 2. 业务校验（编号唯一性、权限等）
 if (monitorEquipRepository.existsByCode(dto.getMonitorCode())) {
 return Result.fail(1001, "监测点编号已存在");
 }
 
 // 3. 企业版落库
 monitorEquipRepository.save(dto);
 
 // 4. 同步园区版（这里是关键！）
 try {
 parkApiClient.pushMonitorEquip(dto);
 } catch (Exception e) {
 // 5. 园区版同步失败的处理（决定了一致性策略）
 log.warn("园区版同步失败，已加入重试队列: id={}", dto.getId(), e);
 retryQueue.push("park_sync", dto); // 异步重试
 // 注意：这里**不要抛异常给前端**，因为企业版已经成功了
 }
 
 return Result.ok();
}

5 个关键决策：

是否同步等待园区版响应？ 答：否，园区版失败不阻断企业版（否则企业用户卡死）

失败后如何重试？ 答：MQ 异步重试 + 死信队列人工介入

如何避免重复同步？ 答：每个端点都带 id（主键），园区版用 upsert 语义

如何追踪同步状态？ 答：每个对象加 sync_status（待同步/已同步/失败）+ sync_time

如何保证最终一致？ 答：定时对账任务（每天凌晨拉取企业版增量 vs 园区版已收，对账差异）

5.3 批量同步的端点设计

1
2


POST /prevent/riskUnit/add-batch
Content-Type: application/json

1
2
3
4
5
6
7


{
 "list": [
 { "id": "1", "riskUnitName": "反应釜 A 单元" },
 { "id": "2", "riskUnitName": "储罐区 B 单元" },
 { "id": "3", "riskUnitName": "装卸区 C 单元" }
 ]
}

批量端点的 3 个原则：

总量限制：单次 ≤ 500 条（超过容易超时/内存溢出）

部分成功语义：返回 data.succeeded / data.failed 两个数组

失败明细可重试：failed[].reason 标明原因，前端可一键重试

六、CRUD 三段式 vs RESTful 的 7 大差异

维度	动作式（这份规范）	RESTful	推荐
新增	`POST /xxx/add`	`POST /xxx`	等价
修改（整对象）	`POST /xxx/update`	`PUT /xxx/{id}`	等价
修改（部分字段）	`POST /xxx/update`	`PATCH /xxx/{id}`	RESTful 更精确
删除	`POST /xxx/delete`	`DELETE /xxx/{id}`	等价
查询单个	`POST /xxx/getById`	`GET /xxx/{id}`	RESTful 天然缓存
查询列表	`POST /xxx/list`	`GET /xxx?page=1&size=20`	RESTful 更标准
查询复杂条件	`POST /xxx/search`	`POST /xxx/search`	等价（因为 GET 装不下复杂 JSON）

实战选型：

CRUD 增删改 → 动作式（少一层 RESTful 心智负担）

查询（特别是 GET）→ RESTful（浏览器/网关/CDN 都能缓存）

复杂搜索（多条件 + JSON body）→ 动作式（POST /search 不可避免）

七、OpenAPI 3.0 自动化生成

这份规范是手写 Markdown 的，但现代化的企业 API 规范应该从代码生成：

7.1 Java + springdoc-openapi

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@RestController
@RequestMapping("/hazard/monitorEquip")
@Tag(name = "重大危险源-监测设备")
public class MonitorEquipController {

 @Operation(summary = "新增监测设备")
 @PostMapping("/add")
 public Result<MonitorEquipVO> add(@Valid @RequestBody MonitorEquipDTO dto) {
 // ...
 }
}

7.2 自动生成 OpenAPI 3.0 + Swagger UI

1
2
3
4
5
6


<!-- pom.xml -->
<dependency>
 <groupId>org.springdoc</groupId>
 <artifactId>springdoc-openapi-ui</artifactId>
 <version>1.7.0</version>
</dependency>

访问 http://{{INTERNAL_HOST}}:8080/swagger-ui.html 即可看到自动生成的接口文档。比手写 Markdown 强 10 倍——前后端联调、自动化测试、Mock 数据都能从 OpenAPI 自动派生。

八、6 大设计原则速记

统一信封：所有响应都是 {code, msg, data, success}，业务成功用 200
Bearer Token：Authorization 头 + 30 天有效期 + HTTPS 强制
模块化 URL：/一级模块/二级模块/动作，动作可选 add/update/delete 或 HTTP 动词
字段类型谨慎：ID/编号/金额 永远用 string，时间用 ISO 8601
批量与同步：单次 ≤ 500 条 + 部分成功 + MQ 异步重试 + 定时对账
OpenAPI 自动化：从代码注解生成文档，不要手写 Markdown

九、典型代码生成（Java + Spring Boot）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


// 统一响应体
@Data
public class Result<T> {
 private String msg;
 private int code;
 private T data;
 private boolean success;
 
 public static <T> Result<T> ok() { return ok(null); }
 public static <T> Result<T> ok(T data) {
 Result<T> r = new Result<>();
 r.setCode(0);
 r.setMsg("成功");
 r.setData(data);
 r.setSuccess(true);
 return r;
 }
 public static <T> Result<T> fail(int code, String msg) {
 Result<T> r = new Result<>();
 r.setCode(code);
 r.setMsg(msg);
 r.setSuccess(false);
 return r;
 }
}

// 鉴权拦截器
@Component
public class AuthInterceptor implements HandlerInterceptor {
 @Override
 public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
 String auth = req.getHeader("Authorization");
 if (auth == null || !auth.startsWith("Bearer ")) {
 throw new AuthException("未登录");
 }
 String token = auth.substring(7);
 // 校验 token：从 Redis 取用户信息
 Long userId = tokenService.getUserIdByToken(token);
 if (userId == null) {
 throw new AuthException("Token 已过期");
 }
 // 放入 ThreadLocal
 UserContext.set(userId);
 return true;
 }
}

十、参考与延伸

OpenAPI 3.0 规范：https://swagger.io/specification/
RFC 6750 - OAuth 2.0 Bearer Token：https://datatracker.ietf.org/doc/html/rfc6750
RESTful API 设计指南（GitHub）：https://docs.github.com/en/rest
Stripe API 设计：https://stripe.com/docs/api（业界标杆）
Google API Design Guide：https://cloud.google.com/apis/design
微软 REST API 指南：https://github.com/microsoft/api-guidelines

下一步：建议直接用 springdoc-openapi（Java）或 swaggo（Go）从代码生成 API 文档；用 Postman / Apifox 维护接口测试用例；用 YApi / Apifox 做 Mock 数据；用 Pact 做消费者驱动的契约测试。

2024+ 视角

2020 年的"统一响应体 + Bearer Token + RESTful"骨架在 2024-2026 年依然成立，但生态发生了几个关键演进：

OpenAPI 3.1 落地：3.0 在 2024 年仍是主流，但 3.1 已对齐 JSON Schema 2020-12 规范，并支持 Webhook 和 API 设计优先（spec-first）模式。Stoplight Elements / Redocly 等文档渲染工具成为新标配。
API 网关与契约测试：
- 网关：Kong 3.x、Apigee、Apache APISIX 3.x（云原生 + eBPF 加速）已成主流
- 契约测试：Pact 2.0 + Pactflow 是消费者驱动测试的工业标准，配合 CI 做兼容性回归
鉴权演进：Bearer Token + JWT 仍是基础，但OAuth 2.1（2024 草案）将 PKCE 设为强制；企业级推荐 OIDC（OpenID Connect） + Keycloak / Auth0 / Authing。
API 安全：OWASP API Security Top 10（2023 版） 把"Broken Object Level Authorization（BOLA）“列为 #1——任何列表/详情接口都要做资源所有权校验。42Crunch / APIsec 提供自动化 API 安全扫描。
GraphQL / gRPC 互补：
- 复杂前端聚合场景：GraphQL（Hasura、Apollo、Yoga）正在替代"网关聚合多个 REST”
- 内部服务通信：gRPC + protobuf 已成事实标准（Envoy/Istio 内部走 xDS/gRPC）
可观测性：API 监控从"看 HTTP 状态码"升级到 RED（Rate/Error/Duration）+ 业务维度 trace。OpenTelemetry 1.x + Jaeger / Tempo 把 traceid 注入 HTTP header，跨服务追踪成为标配。
园区版/双写模式进化：2024 年企业级同步更推荐 CDC（Change Data Capture） ——Debezium 监听 MySQL binlog，Kafka 分发，下游订阅。比"应用层 try-catch 同步双写"更可靠、侵入小。

实战建议更新：

单体 → REST + OpenAPI + 统一信封
微服务 → REST（对外）+ gRPC（对内）+ GraphQL（BFF）
鉴权 → OIDC + OAuth 2.1 + RBAC/ABAC
文档 → Spec-First（OpenAPI 3.1 + Stoplight）
测试 → 契约测试（Pact）+ E2E（Playwright）+ 性能（k6）
同步 → 避免应用层双写，改 CDC + 事件驱动

2020 年这篇的"6 大设计原则"骨架完全成立，2024+ 视角主要补全的是 OAuth 2.1、OWASP API Top 10、CDC 同步、OpenTelemetry 四个维度。

海康摄像头接入萤石云：AppKey/Secret 申请、Token 获取、设备添加、直播地址

Sat, 15 Dec 2018 00:00:00 +0800

一、为什么"萤石云"是海康的官方上云通道

海康威视 2015 年推出"萤石云"（ezviz），是海康官方的 IoT 平台。接入萤石云开放平台有几个典型收益：

远程观看：自带萤石云 App / Web 客户端，无需自建流媒体服务
P2P 打洞：摄像头无需公网 IP，穿透内网直接访问
录像 / 告警 / 云存储：海康官方运维，不占本地存储
多端 SDK：Web / iOS / Android / 小程序 SDK 全有

对接的核心是萤石云开放平台（open.ys7.com）——海康的所有摄像头都能接（不只是萤石云品牌）。

二、硬件准备

2.1 摄像头配置

海康摄像头默认已经支持萤石云接入——只需在摄像头后台开启"萤石云服务"：

1
2
3
4
5
6


1. 摄像头 Web 后台（默认 http://192.168.1.64）
2. 网络 → 平台接入
3. 启用"萤石云"
4. 记下两个关键参数：
 - 设备序列号（9 位数字 / 字母）
 - 验证码（6 位大写字母，印在机身标签上）

关键：设备序列号的字母必须大写——这是萤石云 API 强制的。

2.2 网络要求

摄像头能访问公网（萤石云域名 open.ys7.com）
不需要固定公网 IP（P2P 打洞）
不要把摄像头放在 DMZ——萤石云有白名单校验

三、注册萤石云开放平台账号

3.1 注册入口

地址：https://open.ys7.com/

1
2
3
4
5
6


1. 注册开发者账号
2. 进入"我的应用" → "创建应用"
3. 填写应用名称、类型
4. 创建成功后，拿到：
 - AppKey
 - AppSecret

AppKey 和 AppSecret 是开放平台的唯一身份标识——所有 API 调用都基于这两个参数。

3.2 应用类型选择

Web 应用 —— 浏览器端 JS 调用
移动 App —— iOS / Android
服务端应用 —— 纯后端调用（最常用——服务器拉取设备列表 / 直播地址）

四、获取 accessToken

4.1 接口说明

1
2
3
4
5
6
7


URL: https://open.ys7.com/api/lapp/token/get
Method: POST
Content-Type: application/x-www-form-urlencoded

请求参数：
 appKey: <你的 AppKey>
 appSecret: <你的 AppSecret>

4.2 返回数据

1
2
3
4
5
6
7
8


{
 "data": {
 "accessToken": "at.7jrcjmna8qnqg8d3dgnzs87m4v2dme3l-32enpqgusd-1jvdfe4-uxo15ik0s",
 "expireTime": 1470810222045
 },
 "code": "200",
 "msg": "操作成功!"
}

accessToken 有效期 7 天——需要缓存（不要每次调用都请求一次）。

4.3 错误码

错误码	描述
200	请求成功
10001	参数错误（appKey/appSecret 为空或格式错）
10005	appKey 被冻结
10017	appKey 不存在
10030	appKey 和 appSecret 不匹配
49999	接口异常

4.4 curl 示例

1
2
3


curl -X POST https://open.ys7.com/api/lapp/token/get \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "appKey=YOUR_APPKEY&appSecret=YOUR_APPSECRET"

五、添加设备

5.1 文档地址

https://open.ys7.com/doc/zh/book/index/device_option.html#device_option-api1

5.2 接口

1
2
3
4
5
6
7
8


URL: https://open.ys7.com/api/lapp/device/add
Method: POST
Content-Type: application/x-www-form-urlencoded

请求参数：
 accessToken: <上一步拿到的 accessToken>
 deviceSerial: <设备序列号> # 字母必须大写
 validateCode: <验证码> # 6 位大写字母

5.3 返回示例

1
2
3
4


{
 "code": "200",
 "msg": "操作成功"
}

code: 200 表示添加成功。

5.4 注意事项

设备必须先在摄像头 Web 后台启用萤石云
一个 AppKey 可以添加多个设备——没有数量限制（但单 AppKey 调用频率有限制）
设备添加后立即生效——Web / App 端登录同一个萤石云账号就能看到

六、获取直播地址

6.1 接口

1
2
3


URL: https://open.ys7.com/api/lapp/v2/live/address/get
Method: POST
Content-Type: application/x-www-form-urlencoded

6.2 请求参数

参数	类型	必选	描述
accessToken	String	Y	上一步拿到的 accessToken
deviceSerial	String	Y	设备序列号，限制 50 字符
channelNo	Integer	N	通道号，默认 1
code	String	N	ezopen 协议的视频加密密码
expireTime	Integer	N	过期时长（秒），30 - 720 天
protocol	Integer	N	协议：1-ezopen / 2-hls / 3-rtmp / 4-flv，默认 1
quality	Integer	N	清晰度：1-高清 / 2-流畅
supportH265	Integer	N	是否 H.265：1-需要 / 0-不要求

6.3 返回示例

1
2
3
4
5
6
7
8
9


{
 "code": "200",
 "msg": "操作成功，获取指定有效期的直播地址",
 "data": {
 "id": "...",
 "url": "ezopen://open.ys7.com/BC9729213/1.hd.live",
 "expireTime": 1694764800
 }
}

返回的 url 字段就是直播地址——浏览器 / VLC / 萤石云 App 都能直接播。

6.4 协议对比

协议	浏览器支持	延迟	适用
ezopen	❌（萤石云私有协议）	1-2s	萤石云 App / SDK
hls	✅ Safari 原生 / Chrome 需 video.js	5-10s	Web 端最稳
rtmp	❌ Flash 88+ 已删	1-2s	老项目
flv	✅ via video.js HTTP-FLV	1-2s	Web 端低延迟

七、消息订阅（告警 / 事件推送）

7.1 订阅事件

1
2
3
4
5


curl --location --request POST \
 'https://open.ys7.com/api/open/cloud/ISAPI/Event/notification/subscribeEvent' \
 --header 'User-Agent: apifox/1.0.0 (https://www.apifox.cn)' \
 --data-urlencode 'accessToken=at.your_token_here' \
 --data-urlencode 'deviceSerial=YOUR_DEVICE_SERIAL'

事件类型：

移动侦测（motion）
视频遮挡（videoBlind）
声音异常（audio异常）
IO 报警（外接红外 / 门磁）

7.2 拉取告警列表

1
2
3
4
5


curl --location --request POST \
 'https://open.ys7.com/api/lapp/alarm/device/list' \
 --header 'User-Agent: apifox/1.0.0 (https://www.apifox.cn)' \
 --data-urlencode 'accessToken=at.your_token_here' \
 --data-urlencode 'deviceSerial=YOUR_DEVICE_SERIAL'

返回形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "code": "200",
 "data": [
 {
 "alarmId": "...",
 "alarmName": "移动侦测",
 "alarmTime": "2024-12-15 10:30:00",
 "channelNo": 1,
 "deviceSerial": "..."
 }
 ]
}

八、Java 后端封装

8.1 依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<dependency>
 <groupId>com.squareup.okhttp3</groupId>
 <artifactId>okhttp</artifactId>
 <version>4.12.0</version>
</dependency>
<dependency>
 <groupId>com.alibaba.fastjson2</groupId>
 <artifactId>fastjson2</artifactId>
 <version>2.0.43</version>
</dependency>

8.2 TokenService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


@Service
public class Ys7TokenService {

 private static final String APP_KEY = "your_app_key";
 private static final String APP_SECRET = "your_app_secret";
 private static final String TOKEN_URL = "https://open.ys7.com/api/lapp/token/get";

 // 缓存 token
 private String cachedToken;
 private long expireTime = 0;

 public synchronized String getAccessToken() {
 if (cachedToken != null && System.currentTimeMillis() < expireTime) {
 return cachedToken;
 }

 OkHttpClient client = new OkHttpClient();
 RequestBody body = new FormBody.Builder()
 .add("appKey", APP_KEY)
 .add("appSecret", APP_SECRET)
 .build();

 Request request = new Request.Builder()
 .url(TOKEN_URL)
 .post(body)
 .build();

 try (Response response = client.newCall(request).execute()) {
 String json = response.body().string();
 JSONObject data = JSON.parseObject(json).getJSONObject("data");
 cachedToken = data.getString("accessToken");
 expireTime = data.getLong("expireTime") - 86400_000L; // 提前 1 天刷新
 return cachedToken;
 } catch (IOException e) {
 throw new RuntimeException("获取萤石云 token 失败", e);
 }
 }
}

8.3 设备添加

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


@Service
public class Ys7DeviceService {

 @Autowired
 private Ys7TokenService tokenService;

 public boolean addDevice(String deviceSerial, String validateCode) {
 // 字母必须大写
 deviceSerial = deviceSerial.toUpperCase();
 validateCode = validateCode.toUpperCase();

 OkHttpClient client = new OkHttpClient();
 RequestBody body = new FormBody.Builder()
 .add("accessToken", tokenService.getAccessToken())
 .add("deviceSerial", deviceSerial)
 .add("validateCode", validateCode)
 .build();

 Request request = new Request.Builder()
 .url("https://open.ys7.com/api/lapp/device/add")
 .post(body)
 .build();

 try (Response response = client.newCall(request).execute()) {
 String json = response.body().string();
 return "200".equals(JSON.parseObject(json).getString("code"));
 } catch (IOException e) {
 throw new RuntimeException("添加设备失败", e);
 }
 }
}

九、调用频率限制

萤石云开放平台有调用频率限制：

token 接口：每个 AppKey 每分钟 60 次
设备 / 直播地址接口：每个 AppKey 每分钟 120 次

生产建议：

accessToken 缓存 7 天（设过期前 1 天主动刷新）
设备列表本地缓存**（摄像头不轻易变化）**
直播地址按需获取，短期缓存 5-10 分钟

十、常见 5 个坑

设备序列号字母必须大写——deviceSerial.toUpperCase() 是基本操作
accessToken 每次调 token 接口——会触发频率限制——必须本地缓存
添加设备失败但摄像头 Web 后台能看到萤石云在线——AppKey 没绑定到具体设备——重新走 device/add
直播地址过期——默认 expireTime = 7 天——生产建议设 30 天 + 提前刷新
告警事件收不到——没订阅事件——先调 subscribeEvent 才会推送

十一、安全注意

AppSecret 必须服务端存储——不能放到前端 / 客户端（会被反编译 / 抓包）
设备验证码只用于首次添加——建议添加成功后丢弃，不要长期存数据库
accessToken 不要写日志——走日志脱敏（参考 .claude/docs/0.5-batch-guide.md）

十二、总结

萤石云开放平台 = 海康官方 IoT 云——AppKey/Secret 申请 → token 获取 → 设备添加 → 直播地址
accessToken 7 天有效——必须服务端缓存（避免触发频率限制）
设备序列号 + 验证码——字母必须大写——6 位大写字母印在机身
直播地址协议 = ezopen（私有）/ hls（web 稳）/ flv（web 低延迟）
消息订阅 = subscribeEvent + alarm/device/list 拉取
生产建议 = AppSecret 走服务端 + token 缓存 7 天 + 直播地址 5-10 分钟缓存

参考资料

接口文档模板与 .NET 平台应用场景

Tue, 15 May 2018 00:00:00 +0800

前置知识

至少调用过一个 HTTP API（GET / POST / JSON）
知道什么是 REST、什么是接口
了解任一后端语言（Java / Go / Python 即可）

一份合格的接口文档应该长什么样

2010 年代中后期，微服务、API 经济、OpenAPI 规范逐步走向主流——前后端分离的协作模式倒逼后端必须给前端 / 移动端 / 第三方提供"机器可读 + 人可读"两份接口契约。

一份合格的接口文档必须回答 5W1H：

维度	回答什么
What	接口是什么？功能描述
Where	接口在哪？URL / IP / 端口
When	何时调用？超时、重试、限流
Who	谁可以调？鉴权方式
Which	进出什么数据？字段含义、类型、必填
How	怎么调？HTTP 方法、Headers、错误码

下面是一份可直接复用的 Markdown 模板。

一、接口文档 Markdown 模板

1.1 顶层信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 接口名

## 接口协议：http / https

## 接口地址：写明需要调用的地址或 IP

## 接口端口：服务开启的端口号

## 目录（自动生成）

[TOC]

1.2 单接口详细说明

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


## 1. 简单描述接口

### 接口功能

> 描述这个接口是干什么用的，基本逻辑是什么

### URL

> 接口调用地址，例：`/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> `json` / `html` / `xml`

### HTTP 请求方式

> `GET` / `POST` / `PUT` / `DELETE`

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| id | 是 | string | 实体唯一标识 |
| name | 否 | string | 名称（模糊匹配） |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码，200=成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| data.id | string | 实体 ID |
| data.name | string | 实体名称 |

### 接口示例

> 调用地址：`http://api.example.com:8080/api/rest/...`

#### 请求参数

```json
{
 "id": "10001"
}

返回结果

1
2
3
4
5
6
7
8


{
 "code": 200,
 "msg": "成功",
 "data": {
 "id": "10001",
 "name": "示例"
 }
}

错误码

错误码	含义	处理建议
200	成功	-
400	参数错误	检查请求参数
401	未授权	重新登录获取 token
403	无权限	联系管理员
404	资源不存在	检查 id
500	服务器异常	联系后端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53



### 1.3 完整示例

```markdown
# 危险废物地图 - 企业详情查询

## 接口协议：https

## 接口地址：api.example.com

## 接口端口：443

## 1. 简单描述接口

### 接口功能

> 根据企业 ID 查询企业基本信息、许可证信息、危废产生量

### URL

> `/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> json

### HTTP 请求方式

> GET

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| entId | 是 | string | 企业 ID |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码 |
| msg | string | 描述 |
| data | object | 企业信息 |
| data.entName | string | 企业名称 |
| data.legalPerson | string | 法人 |
| data.address | string | 地址 |
| data.licenses | array | 许可证列表 |

### 接口示例

> 地址：`https://api.example.com/api/rest/wasteMap/entInfo/getEntInfoById?entId=10001`

#### 请求 Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9… Content-Type: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19



#### 返回结果

```json
{
 "code": 200,
 "msg": "成功",
 "data": {
 "entName": "某环保科技公司",
 "legalPerson": "张三",
 "address": "江苏省南京市江宁区...",
 "licenses": [
 {
 "licNo": "HW-2024-001",
 "validUntil": "2027-12-31"
 }
 ]
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42



## 二、接口文档工具链

### 2.1 OpenAPI 3.0（Swagger）

2015 年 Swagger 规范被 SmartBear 捐给 Linux 基金会，演化为 **OpenAPI 3.0**——机器可读的接口定义标准。

```yaml
# openapi.yaml
openapi: 3.0.0
info:
 title: 示例 API
 version: 1.0.0
 description: 危险废物地图服务
servers:
 - url: https://api.example.com
paths:
 /api/rest/wasteMap/entInfo/getEntInfoById:
 get:
 summary: 查询企业详情
 parameters:
 - name: entId
 in: query
 required: true
 schema:
 type: string
 responses:
 '200':
 description: 成功
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/EntInfo'
components:
 schemas:
 EntInfo:
 type: object
 properties:
 entName:
 type: string
 legalPerson:
 type: string

工具链：

Swagger UI：把 YAML 渲染成可调试的网页（/swagger-ui/index.html）
Swagger Editor：在线编辑器
Swagger Codegen：自动生成 Java / Go / TS 客户端 SDK
Springdoc / springfox：Java 注解自动生成 OpenAPI YAML

2.2 API 文档平台

工具	优势	适合
Swagger / OpenAPI	行业标准	任何规模
Postman	协作 + 调试	前后端协作
Apifox	国产、UI 友好	中小团队
ShowDoc	国产、轻量	内部文档
语雀 / 飞书	知识库	业务文档为主
ReadMe	商业化、交互式	SaaS 产品

2.3 文档即代码（Doc-as-Code）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Git 仓库结构
docs/
├── api/
│ ├── openapi.yaml # 接口定义
│ ├── errors.md # 错误码字典
│ └── auth.md # 鉴权说明
├── guides/
│ ├── quickstart.md
│ └── best-practices.md
└── README.md

版本随代码走（PR review 改接口必改文档）
CI 自动部署到内网 / 公网（GitHub Pages + 自动构建）
评审流程与代码一致

三、.NET 平台应用场景

3.1 .NET Framework vs .NET Core

维度	.NET Framework	.NET Core / .NET 5+
平台	Windows only	跨平台（Win / macOS / Linux）
开源	闭源	MIT 开源（2014 年起）
性能	一般	比 Framework 快 2-10 倍
微服务	不友好	一等公民
容器化	难	镜像 100MB-
现状	维护模式	主流

2016 年微软开源 .NET Core 1.0、2017 年发布 2.0、2020 年 .NET 5 统一品牌、2024 年 .NET 9 已是事实标准。

3.2 七大应用领域

① Web 应用

ASP.NET Core MVC / Razor Pages / Blazor：

1
2
3
4
5
6
7
8
9


// Razor Page
@page
@model IndexModel
@{
 ViewData["Title"] = "首页";
}

<h1>@Model.Greeting</h1>
<p>当前时间：@DateTime.Now</p>

适合：企业内网系统、SaaS 后台、CMS。

② 移动开发

Xamarin（2011 年起）+ .NET MAUI（2022 年起）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// .NET MAUI
public partial class MainPage : ContentPage
{
 public MainPage()
 {
 InitializeComponent();
 }

 void OnCounterClicked(object sender, EventArgs e)
 {
 count++;
 CounterLabel.Text = $"点击 {count} 次";
 }
}

一份 C# 代码，编译成 iOS / Android / Windows / macOS 原生应用。

③ 桌面应用程序

WPF（Windows Presentation Foundation）——Windows 桌面 UI
WinForms —— 老式 Windows 桌面
WinUI 3 —— 现代 Windows 11 风格
Avalonia —— 跨平台桌面 UI（类似 Flutter 思路）

适合：企业内部工具、IDE 插件、客户端软件。

④ 微服务与容器

ASP.NET Core + Docker + Kubernetes：

1
2
3
4
5


# 5MB 镜像级别
FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyService.dll"]

.NET 9 + NativeAOT（Ahead-of-Time）编译后镜像 50MB，启动 < 100ms——对标 Go 的部署体验。

⑤ 云应用程序

Azure 一等公民，AWS / 阿里云 / 腾讯云都有 SDK：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// Azure Functions 写法（无服务器）
public class HttpExample
{
 [Function("HttpExample")]
 public async Task<HttpResponseData> Run(
 [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
 {
 var response = req.CreateResponse(HttpStatusCode.OK);
 await response.WriteStringAsync("Hello from Azure Functions!");
 return response;
 }
}

⑥ 物联网（IoT）

.NET nanoFramework —— 跑在 STM32 / ESP32 嵌入式芯片
Meadow —— IoT 主板，完整 .NET 运行时
Azure IoT Hub SDK —— 云端接入

⑦ 机器学习

ML.NET —— 微软的机器学习框架，2018 年开源：

1
2
3
4
5
6


// 训练一个情感分析模型
var mlContext = new MLContext();
var data = mlContext.Data.LoadFromTextFile<SentimentData>("sentiment.csv", hasHeader: true);
var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "Text")
 .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression());
var model = pipeline.Fit(data);

也支持调用 ONNX 模型、TensorFlow .NET 绑定。

⑧ 游戏

Unity 是全球最大游戏引擎（手游市场 50%+），C# 是 Unity 的唯一脚本语言。王者荣耀、原神、纪念碑谷都用 C# / Unity。

四、.NET 选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


新项目，应该选什么 .NET？
│
├─ Web / 微服务？
│ ├─ Windows only + 老系统集成 → ASP.NET (.NET Framework 4.8)
│ └─ 跨平台 / 容器 / 云原生 → ASP.NET Core (.NET 8 / 9)
│
├─ 桌面？
│ ├─ 内部工具 / Windows only → WPF / WinForms
│ ├─ 现代 Windows UI → WinUI 3
│ └─ 跨平台桌面 → Avalonia / .NET MAUI
│
├─ 移动？
│ ├─ iOS / Android / Windows 跨平台 → .NET MAUI
│ └─ Unity 游戏 → Unity + C#
│
├─ 嵌入式 / IoT？
│ ├─ 资源极受限（< 256KB RAM）→ C / C++
│ └─ STM32 / ESP32 → .NET nanoFramework
│
└─ ML？
 └─ ML.NET / 调 ONNX / 调 TensorFlow.NET

五、为什么 2018 年 .NET 突然火了

跨平台 + 开源：2014 年 .NET Core 开源后，Linux 服务器也能跑 C#——Linux 工程师不再鄙视 .NET
性能飞升：TechEmpower Round 14 基准测试，ASP.NET Core 超过 Node.js、Go、Java
VS Code + Rider：跨平台 IDE 体验不输 Visual Studio
云原生友好：镜像小、启动快、K8s 一等公民
企业级生态：Entity Framework Core、xUnit、Serilog、MediatR——dotnet add package 一行解决

六、下一步

入门：.NET 官方文档 https://learn.microsoft.com/dotnet/，先跑通 dotnet new web
Web 框架：ASP.NET Core 8 / 9 Minimal API
微服务：Steeltoe（Spring Cloud 之于 Spring Boot）
测试：xUnit + FluentAssertions + NSubstitute
ORM：EF Core（官方）、Dapper（轻量）、FreeSQL（国产）

参考资料

.NET 官方文档：https://learn.microsoft.com/dotnet/
OpenAPI 规范：https://spec.openapis.org/oas/v3.0.3
Swagger 工具链：https://swagger.io/tools/
ASP.NET Core 源码：https://github.com/dotnet/aspnetcore
.NET 基金会：https://dotnetfoundation.org/