若项目需要规范开发者录入的接口参数名,可在「项目」-「设置」-「通用设置」中,开启参数词条校验功能,开启该功能后,接口与数据类型中的参数名必须预先在参数词条内定义,否则无法保存。
「项目组管理员」可以在「公共资源库」或「项目」内创建参数词条,「公共资源库」内创建的参数词条会对整个项目组生效,我们称之为项目组词条。「项目」内创建的参数词条仅对当前项目生效,我们称之为项目词条。此外 NEI 平台预先创建了 60 个高频参数名(详见下文),我们称之为系统预置词条。
参数词条创建后,「项目组管理员」可在「项目」-「资源」-「参数词条」内设置参数词条的禁用、启用状态。开发者在录入接口时,若输入处于禁用状态的参数名,则无法保存。
参数词条的禁用状态存在覆盖关系,优先级顺序为:项目 > 项目组 > 系统预置。即项目、项目组若都同时对一个参数词条设置了禁用/启用,则该词条的禁用的状态以项目为准。
在创建参数词条时,用户可以输入该词条的联想词。如管理员创建了一个名为 startTime 的参数词条,并设置了两个联想词 startDate, startMoment。 则后续开发者在录入接口参数名时若输入了 startDate 且 startDate 未在参数词条内定义,则无法保存,同时 NEI 会提示用户使用 startTime。
若开发者输入了未在参数词条内定义的参数名,且未命中管理员定义的联想词时,NEI 平台默认会使用 Levenshtein Distance 算法,从参数词条中选择 Levenshtein Distance 小于等于 2 的词条,推荐给开发者。
NEI 平台可以从 JSON 文件中批量导入创建参数词条,JSON 文件需符合如下格式:
[{
"name": "startTime", // 参数词条名,必填字段
"associatedWord": "startDate, startMoment", // 联想词,选填字段
"description": "this is a description text" // 描述, 选填字段
},{
...
}
]
NEI 平台会从项目已创建的接口、数据类型中找出已有的参数名,并根据使用频次进行排序,管理员可在此快速创建一份项目的参数词条。
建议管理员经过筛选后再录入参数词条,否则可能会失去开启参数词条校验的意义。
当前系统预置了 60 个高频参数词条,会不定期根据开发者反馈新增系统预置词条。
系统预置参数词条 |
---|
account |
accountId |
accountName |
address |
age |
avatar |
avatarUrl |
beginDate |
beginTime |
birthday |
code |
count |
createDate |
createTime |
creator |
creatorId |
creatorName |
data |
description |
endDate |
endTime |
from |
gender |
id |
image |
imageUrl |
list |
logo |
member |
memberId |
message |
mobile |
name |
nickname |
number |
page |
pagination |
password |
phone |
record |
required |
result |
size |
startDate |
startTime |
status |
success |
telephone |
time |
timestamp |
title |
total |
type |
updateTime |
url |
user |
userId |
userName |
value |
若项目开启参数词条校验后,需要录入不符合参数词条规范的老接口,可以使用下述方法临时关闭检查功能:
- 在浏览器的控制台中输入 sessionStorage['not-check-word-stock'] = true。
- 然后刷新页面就可以录入老接口了。
如果想重新开启检查功能,只要关闭当前标签页重新打开,或者重启浏览器即可。