FieldExtendsAPIController（字段扩展管理 API）¶

用户中心模块的字段扩展域 CRUD/查询控制器，提供用户/部门/企业域扩展字段配置的创建、更新、查找、删除、按 FID 查询、按表名查询、批量删除、清除字段数据、按类型+表名分页查询、按标签+域查询单条等能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（FieldExtendsAPI 接口），属于后端服务间数据面接口。

控制器全限定名：cn.myapps.usercenter.controller.FieldExtendsAPIController
接口（Feign 契约）：cn.myapps.usercenter.controller.FieldExtendsAPI
Tag：字段扩展管理
类级 @RequestMapping：${myapps.context-path.usercenter:}/fieldextends
基址：<host>/usercenter/fieldextends
独立部署（obpm-usercenter-war/obpm-usercenter-consul）：server.servlet.context-path=/usercenter，占位符 ${myapps.context-path.usercenter:} 缺省为空，故实际基址为 <host>:<port>/usercenter/fieldextends（war 端口 8080，consul 端口 8088）。
统一部署（obpm-lite）：server.servlet.context-path=/，yml 显式配置 myapps.context-path.usercenter=/usercenter，故实际基址同样为 <host>:8888/usercenter/fieldextends。
接口类型：REST 资源

公共说明¶

鉴权¶

（据源码）usercenter 模块本身**不定义**任何安全过滤器或鉴权拦截器，仅注册 PersistenceHandlerInterceptor（用于 DAO 资源清理——事务提交与 Hibernate Session 关闭，不做权限判断）。本控制器 /fieldextends/** 路径下所有端点**不做用户级身份校验**——既不读取 accessToken，也不读取 adminToken/designerToken，控制器方法内也不调用任何 getUser() 之类方法。

usercenter 作为共享库被宿主服务加载后，会继承 obpm-common 提供的 CommonSecurityFilter（由 CommWebMvcConfig 以 @Bean 注册，URL 模式 /*，order=-1，详见 index.md「鉴权说明」），对 /fieldextends/** 的影响仅限：

HTTP 方法限制：未携带合法 systemToken 请求头时，仅允许 GET/POST/HEAD/OPTIONS 方法；直接发起 PUT/DELETE/PATCH 等请求会被 CommonSecurityFilter 以 HTTP 405（HTML 错误页，无 JSON 体）拒绝。
systemToken 放行：携带合法 systemToken 请求头（系统间 Feign 调用，JWT 内 username 固定为 systemToken）的请求被标记 pass=true 并绕过上述方法限制——这是本控制器 PUT /update、PUT /cleanFieldData、DELETE /remove/{id}、DELETE /deleteFieldExtendsByIds 在生产中正常工作的前提。

结论：本控制器的真实访问控制依赖**网络层隔离**（仅由可信的内部服务经 Feign 调用，附 systemToken 请求头），并非用户令牌。终端用户不应直接访问这些端点。

响应结构¶

本控制器不使用统一 Resource 结构（与 ../index.md「统一响应结构」不同）。响应遵循以下规则：

情形	HTTP 状态	响应体
返回值为 `void` 的方法（创建/更新/删除/批量删除/清除字段数据）成功	200	空响应体
返回值为领域对象/集合/包装类型的方法成功	200	直接序列化的对象 JSON（如 `FieldExtendsPO`、`List<FieldExtendsPO>`、`DataPackage<FieldExtendsPO>`），不包裹 `errcode`/`errmsg`/`data`/`errors`
业务/系统异常	500	`{"errcode":500,"errmsg":"<异常信息>"}`（由 obpm-common 的 `CommonsExceptionResolver` 全局异常处理器渲染，仅含 `errcode`/`errmsg` 两字段，无 `data`/`errors`）
HTTP 方法不被允许（无 `systemToken` 的 `PUT`/`DELETE`）	405	HTML 错误页（由 `CommonSecurityFilter` 直接返回）
系统启动中	500	HTML 错误页（由 `CommonSecurityFilter` 直接返回）

数据模型：`FieldExtendsPO`¶

返回的 FieldExtendsPO 继承自 AuthtimeValueObject，表示一条「用户/部门/企业域表」的自定义扩展字段配置。主要字段：fid（主键，getId()/setId() 实际代理读写 fid）、forTable（字段所属表标识，常量 TABLE_USER/TABLE_DEPT/TABLE_DOMAIN 分别对应「用户表/部门表/企业域表」）、name（字段名，对应实体上的 field1/field2… 这类持久化属性，前端调用 getValue() 时会将其首字母大写拼成 getXxx 反射取值）、label（字段标签）、type（字段类型，常量 TYPE_STRING/TYPE_DATE/TYPE_NUMBER/TYPE_CLOB 分别对应字符串/日期/数字/大字段）、isNotNull（是否必填）、enabel（是否在列表中显示，源码原拼写非 enable）、sortNumber（排序号，值小者靠前）、options（选项配置）、isReadonly（是否只读）、isSupportSearch（是否支持查询）、isSupportImport（是否支持导入）。

分页结构：`DataPackage<FieldExtendsPO>`¶

queryByTypeAndForTable 返回 cn.myapps.common.data.DataPackage<FieldExtendsPO>，标准字段为 datas（当前页数据集合）、rowCount（总行数）、pageNo（当前页码）、linesPerPage（每页行数）等。

命名约定¶

本控制器若干标识符为源码原始拼写，调用时须保持一致：方法 qeuryFieldByLabelAndDomain（应为 query）、字段 enabel（应为 enable）、查询关键字参数名 sm_name 等。本文档沿用源码原拼写。

1. 创建字段扩展¶

创建新的字段扩展配置。事务保护：失败回滚。

接口类型：REST 资源
请求方式：POST
请求路径：/create（完整：<host>/usercenter/fieldextends/create）
鉴权：内部（建议经 systemToken 的 Feign 调用；直接调用因 POST 方法不被 CommonSecurityFilter 拦截故技术上无需 token，但本控制器为内部数据面接口）
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
body	body	`FieldExtendsPO`	是	字段扩展信息，通常包含 `forTable`、`name`、`label`、`type`、`domainId`（写入所属域）等

请求示例¶

POST /usercenter/fieldextends/create HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "forTable": "tableUser",
  "name": "field1",
  "label": "工号",
  "type": "string",
  "isNotNull": true,
  "sortNumber": 1
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

2. 更新字段扩展¶

更新现有字段扩展配置。事务保护：失败回滚。

接口类型：REST 资源
请求方式：PUT
请求路径：/update（完整：<host>/usercenter/fieldextends/update）
鉴权：内部（PUT 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
body	body	`FieldExtendsPO`	是	待更新字段扩展（须含主键 `fid`），可携带需更新的字段

请求示例¶

PUT /usercenter/fieldextends/update HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "fid": "__FE001",
  "label": "员工工号",
  "isNotNull": false
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

3. 根据 ID 查询字段扩展¶

根据字段扩展 ID（fid）查询单条字段扩展配置。

接口类型：REST 资源
请求方式：GET
请求路径：/find/{id}（完整：<host>/usercenter/fieldextends/find/{id}）
鉴权：内部
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	字段扩展 ID（即 `fid`）

请求示例¶

GET /usercenter/fieldextends/find/__FE001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 FieldExtendsPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定（通常返回 null 或抛异常进入 CommonsExceptionResolver）。

成功示例：

{
  "fid": "__FE001",
  "forTable": "tableUser",
  "name": "field1",
  "label": "工号",
  "type": "string",
  "isNotNull": true,
  "sortNumber": 1
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

4. 根据 ID 删除字段扩展¶

根据字段扩展 ID（fid）删除单条字段扩展配置。事务保护：失败回滚。

接口类型：REST 资源
请求方式：DELETE
请求路径：/remove/{id}（完整：<host>/usercenter/fieldextends/remove/{id}）
鉴权：内部（DELETE 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	字段扩展 ID（即 `fid`）

请求示例¶

DELETE /usercenter/fieldextends/remove/__FE001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

5. 根据 FID 查询字段扩展¶

根据字段扩展 fid 查询匹配的字段扩展列表。

接口类型：REST 资源
请求方式：GET
请求路径：/queryFieldExtendsByFid（完整：<host>/usercenter/fieldextends/queryFieldExtendsByFid）
鉴权：内部
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
fid	query	string	是	字段扩展 FID

请求示例¶

GET /usercenter/fieldextends/queryFieldExtendsByFid?fid=__FE001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 List<FieldExtendsPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "fid": "__FE001", "forTable": "tableUser", "name": "field1", "label": "工号" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

6. 批量删除字段扩展¶

根据 FID 列表批量删除字段扩展。事务保护：失败回滚。

接口类型：REST 资源
请求方式：DELETE
请求路径：/deleteFieldExtendsByIds（完整：<host>/usercenter/fieldextends/deleteFieldExtendsByIds）
鉴权：内部（DELETE 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
body	body	`List<String>`	是	待删除的 FID 列表

请求示例¶

DELETE /usercenter/fieldextends/deleteFieldExtendsByIds HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

["__FE001", "__FE002", "__FE003"]

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

7. 根据表名查询字段扩展¶

根据域 ID 与目标表标识查询该表上配置的全部字段扩展。

接口类型：REST 资源
请求方式：GET
请求路径：/queryFieldExtendsByTable（完整：<host>/usercenter/fieldextends/queryFieldExtendsByTable）
鉴权：内部
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	域 ID
forTable	query	string	是	字段所属表标识（取值如 `tableUser`/`tableDept`/`tableDomain`）

请求示例¶

GET /usercenter/fieldextends/queryFieldExtendsByTable?domainId=__DMN001&forTable=tableUser HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 List<FieldExtendsPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "fid": "__FE001", "forTable": "tableUser", "name": "field1", "label": "工号" },
  { "fid": "__FE002", "forTable": "tableUser", "name": "field2", "label": "性别" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

8. 清除字段数据¶

清除指定域、指定表上某个字段列的全部数据（用于字段被废弃或重命名前的清理）。事务保护：失败回滚。

接口类型：REST 资源
请求方式：PUT
请求路径：/cleanFieldData（完整：<host>/usercenter/fieldextends/cleanFieldData）
鉴权：内部（PUT 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	域 ID
tableName	query	string	是	目标物理表名（如 `tb_user`、`tb_department`）
fieldName	query	string	是	待清除的字段列名（如 `field1`）

请求示例¶

PUT /usercenter/fieldextends/cleanFieldData?domainId=__DMN001&tableName=tb_user&fieldName=field1 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

9. 根据类型和表名分页查询字段扩展¶

根据域 ID、字段类型、所属表、所属分类（belong）分页查询字段扩展配置。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByTypeAndForTable（完整：<host>/usercenter/fieldextends/queryByTypeAndForTable）
鉴权：内部
Tag：字段扩展管理

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	域 ID
type	query	string	是	字段类型（如 `string`/`date`/`number`/`clob`）
table	query	string	是	字段所属表标识（参数名为 `table`，非 `forTable`）
belong	query	string	是	所属分类
page	query	int	是	页码（1 起）
lines	query	int	是	每页条数

请求示例¶

GET /usercenter/fieldextends/queryByTypeAndForTable?domainId=__DMN001&type=string&table=tableUser&belong=user&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<FieldExtendsPO> 对象 JSON（不包裹 Resource），含 datas、rowCount、pageNo、linesPerPage 等字段。

成功示例：

{
  "datas": [
    { "fid": "__FE001", "forTable": "tableUser", "name": "field1", "type": "string", "label": "工号" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

10. 根据标签和域查询字段¶

根据字段标签（label）、域 ID、所属表与所属分类查询单条匹配的字段扩展配置。

接口类型：REST 资源
请求方式：GET
请求路径：/qeuryFieldByLabelAndDomain（完整：<host>/usercenter/fieldextends/qeuryFieldByLabelAndDomain）
鉴权：内部
Tag：字段扩展管理

注：路径中的 qeury 为源码原始拼写（应为 query），调用时须保持一致。

请求参数¶

参数名	位置	类型	必填	说明
label	query	string	是	字段标签
domainId	query	string	是	域 ID
forTable	query	string	是	字段所属表标识
belong	query	string	是	所属分类

请求示例¶

GET /usercenter/fieldextends/qeuryFieldByLabelAndDomain?label=工号&domainId=__DMN001&forTable=tableUser&belong=user HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 FieldExtendsPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定。

成功示例：

{
  "fid": "__FE001",
  "forTable": "tableUser",
  "name": "field1",
  "label": "工号",
  "type": "string"
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

FieldExtendsAPIController（字段扩展管理 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：FieldExtendsPO¶

分页结构：DataPackage<FieldExtendsPO>¶

命名约定¶

1. 创建字段扩展¶

请求参数¶

请求示例¶

响应¶

2. 更新字段扩展¶

请求参数¶

请求示例¶

响应¶

3. 根据 ID 查询字段扩展¶

请求参数¶

请求示例¶

响应¶

4. 根据 ID 删除字段扩展¶

请求参数¶

请求示例¶

响应¶

5. 根据 FID 查询字段扩展¶

请求参数¶

请求示例¶

响应¶

6. 批量删除字段扩展¶

请求参数¶

请求示例¶

响应¶

7. 根据表名查询字段扩展¶

请求参数¶

请求示例¶

响应¶

8. 清除字段数据¶

请求参数¶

请求示例¶

响应¶

9. 根据类型和表名分页查询字段扩展¶

请求参数¶

请求示例¶

响应¶

10. 根据标签和域查询字段¶

请求参数¶

请求示例¶

响应¶

数据模型：`FieldExtendsPO`¶

分页结构：`DataPackage<FieldExtendsPO>`¶