规范#

请求路径#

规则#

请求路径的格式遵循 /main-api/{version}/{moduleName}/{entityName}/{methodName}。

示例#

例如，/main-api/v1/device/talk-server/updateById 就是一个符合规则的请求路径示例。

请求结构 (Api request)#

鉴权方式#

可以通过登录接口获取 authorization。在需要鉴权的接口中，有两种方式添加鉴权信息：一是在 HTTP 请求头中添加 Authorization 值；二是在 URL 中添加 Authorization 参数。以下是示例代码：

1{
2    headers: {
3        Accept: 'application/json;charset=UTF-8',
4        'Content-Type': 'application/json',
5        'Authorization': `Bearer ${loginUserStore.authorization}`
6    },
7    credentials: 'include',
8    mode: 'cors',
9    cache: 'no-cache'
10}

1`/system-api/user-center/user/logind?Authorization=${loginUserStore.authorization}`

规则#

请求结构需符合 OpenAPI 3.0 规范。

示例#

1{
2  "deviceId": "string",
3  "deviceModelId": "string",
4  "orgId": "string",
5  "deviceNo": "string",
6  "name": "string",
7  "intro": "string",
8  "state": "string",
9  "installedLocation": "string",
10  "installedTime": "2025-06-10T09:36:05.709Z",
11  "childTableName": "string",
12  "revision": 0,
13  "tenantId": "string",
14  "janusNo": "string",
15  "stunServer": "string",
16  "turnServer": "string",
17  "turnUsername": "string",
18  "turnCredential": "string",
19  "sourceUsername": "string",
20  "sourceTenantId": "string",
21  "sourceDeviceId": "string",
22  "talkServerId": "string",
23  "domainName": "string",
24  "port": 0
25}

响应结构 (Api response)#

规则#

• status: 响应状态码，其默认值为 200，该状态码能够直观地反映出请求响应的大致情况。
  • 200: 成功执行请求，没有发生任何错误。
  • 400: 对象验证失败时抛出。常见场景包括：直接通过验证器（如 Validator）对对象进行校验（如 validator.validate(object)），或在框架（如 Spring、Hibernate）自动触发验证逻辑时（如服务层参数校验、JPA 实体持久化前的约束检查）。当对象的属性违反 @NotEmpty、@Size、@Pattern 等验证注解定义的规则时，所有违反的约束会被收集为 ConstraintViolation 集合，最终封装成该异常，用于集中处理参数或实体的合法性校验失败问题。
  • 401: 身份验证异常，会在认证环节失败时出现。常见场景有：用户登录时输入的用户名或密码有误，无法通过验证；使用的令牌（如 JWT、OAuth2 令牌）无效、过期或者格式不对；请求头中缺少必要的认证信息，像基本认证的 Authorization 头；用户尝试使用禁用、锁定或过期的账户登录。此时，Spring Security 会抛出该异常，阻止用户继续访问受保护资源。
  • 403: 拒绝访问异常，通常发生在用户已通过认证（登录）但缺乏访问目标资源权限的场景，例如请求的 URL 或方法所需角色、权限表达式（如 hasRole、hasAuthority）与用户实际权限不匹配，匿名用户或 “记住我” 用户访问受限资源，自定义访问决策逻辑拒绝（如 AccessDecisionVoter 投票失败），以及请求方法、CSRF 校验、会话权限变更等配置导致的授权失败。核心原因是用户认证通过但授权（权限检查）未通过。
  • 422: 业务逻辑验证失败。这意味着虽然请求本身可能是有效的，但在尝试执行特定业务功能时发现了问题。例如，如果某个设备ID不存在于系统中，那么即使请求格式正确，也会因为找不到相关联的数据而产生此类错误。同样地，具体的原因会在error字段中给出。
  • 500: 发生了内部服务器错误，这通常意味着后端代码遇到了某种未预料的情况（如数据库操作失败）。此时，用户界面只显示"System Error"，但详细的错误信息记录下来以供开发者诊断问题。
  • 1000: 出现于 HTTP 请求 / 响应的消息转换过程失败时，主要场景包括：请求体（如 JSON/XML）无法转换为目标对象（格式错误、类型不匹配等），或响应体对象无法序列化为指定格式（如序列化规则冲突、字段无法处理），本质是数据格式与目标类型间的转换逻辑失败，常见于前后端数据格式不匹配或消息转换器配置问题。
  • 1001: 通常出现在控制器方法的参数验证失败场景。当使用 @Valid 或 @Validated 注解对方法参数（如实体类、基本类型或自定义参数）进行校验时，若客户端请求的参数不符合校验规则（如 @NotEmpty、@Size、@Pattern 等注解定义的约束），Spring 会在参数绑定过程中触发验证逻辑。若验证不通过，会将所有错误信息封装成 BindingResult，并抛出 MethodArgumentNotValidException。例如，前端传递的表单数据缺失必填字段、字符串长度超出限制、格式不符合正则要求等，都会导致该异常，其本质是参数绑定与校验失败的统一封装，便于集中处理请求参数的合法性问题。
• error: 错误描述信息，此为可选字段，仅在出现异常情况时才会返回相关内容，以便使用者清晰知晓出现问题的具体缘由。
• timestamp: 响应时间戳
• path: 请求路径
• extraData: 扩展数据, Map<String, Object> 类型，用于存储额外的、非标准的数据
• data: 响应数据，此为可选字段，仅在实际有数据需要返回时，才会呈现相应的内容。

示例#

1{
2  "timestamp": 0,
3  "status": 200,
4  "path": "/system-api/user-center/user/logind",
5  "extraData": {
6    "additionalProp1": {},
7    "additionalProp2": {},
8    "additionalProp3": {}
9  },
10  "data": null
11}