表里每个字段都该有一行说得清它是什么的说明。这一行写不写，决定的不是代码好不好看，是几年后换人接手时，要不要挨个打电话去问当初写这段的那个人。省下的那点敲键盘时间，后来都要用电话补回去。

下面九个问题，按从建表到接手的顺序摆。每题给一个能直接落地的做法，再用技术上的实情和行内常见做法交叉核。

数据字典到底要记哪些东西，只记表名够不够？

只记表名不够，要记到字段一级：这一格存什么、取值范围、谁写的、什么时候写。四件缺哪一件，后来都只能靠猜。表名只解决东西在哪，字段说明才解决这一格是什么意思。

四件里，取值范围这一项被省掉的情形尤其多。省掉的后果很具体：同一个状态列，有人写 0 表示未处理、有人写 0 表示已关闭，两拨人各自在自己的分支上跑得好好的，合到一起就是一批状态倒挂的数据。

谁写的、什么时候写这两件，是为了让字典本身可信。没有出处的说明，过一任就没人敢改；有出处的，至少能找到人来问一句。

有个不用花工夫的验证办法：随便挑十张表，让一个没参与开发的人只看字典说清每张表是干什么的。说得清八张以上，字典算能用；不到一半，那本字典只是写给写的人自己看的。

字段名用拼音缩写省事，后来会出什么问题？

省的是敲键盘那几秒，付的是长期的解释成本。缩写本身不算错，错在没有配套说明——khjssj 这种名字，除了当初敲它的人谁都读不出来，而那个人往往已经不在这摊事上了。

这不是风格问题，是可维护性问题。字段名承担两个职责：给人看、给程序认。给程序认的那部分怎么起都行，给人看的那部分一旦丢失，每次改动前都要先考古。

可行的折中是保留业务语义在前、缩写在后，比如用 khmc_客户名称 这种双写；或者干脆统一用可读的名字，由字典补一份缩写对照。两种都比纯缩写好接手。

改名的代价要提前算清：动一个字段名，牵动的是索引、视图、导出模板、对账脚本。已经跑了几年、被引用了上百处的那种，改名不如加注释。这也是为什么字典比命名更该先做。

注释写在哪一层，写在代码里和写在库里有什么区别？

两处都要有，作用不同。写在库里的是给使用方和后来接手的人看，写在代码里的是给改代码的人看。只写在代码里的，字典一导出来就是空的；只写在库里的，逻辑一变注释就过期。

库里那一层的好处是可查、可导出、能跟权限一起管。代码里那一层的好处是跟着逻辑走、改的时候不容易漏。缺一层的，出问题的方向不一样：缺库里那层，接手的人要先读一遍代码；缺代码那层，注释和逻辑各走各的。

过期注释比没有注释更麻烦。有人照着一条三年前的说明去理解一个已经改过两次的字段，判断会比完全不知道更偏。

一个实用的办法是给说明加时间戳：这条说明什么时候写的、对应哪次改动。查的时候一眼能看出它是不是还新鲜。

谁来维护这份字典，写代码的人走了怎么办？

维护责任跟着岗位走，不跟着人走。可行的做法是每次改动必须同步改说明，改说明进流程、进评审，不写就不合入。落在某个人身上的，那个人一离职，字典就开始腐烂。

把改说明挂进流程，比事后补省力。事后补的成本随时间上升：刚改完还记得清，半年后要重新读代码才能补，而读代码的时候又会怀疑自己当初是不是改漏了别处。

还要有一个人兜底做核对：隔一段时间抽几张表，把字典和实际结构对一遍，不一致的当场补。抽的比例不用高，能发现偏差就够。

这件事和权限分层是同一个逻辑里的两件：谁能改结构、谁只能看结构，要分开。改结构的人不受约束，字典迟早跟结构脱节。客户资料留存那一类表的说明更该写清：谁填、凭什么填、留着给谁看，三句写完，那一列才不只是个空框。

做居间的团队里，同一套库往往被几拨人轮着改，三五年下来结构没大动、说明早就散了的很常见。这时补的其实不是文档，是把已经流失的那部分共识重新找回来。

状态字段那种 0 和 1，怎么记才不会被各人理解成两回事？

不要靠约定，要靠一张对照表。取值、含义、由谁改、改的时候要不要走审批，四列写死在一处。写在文档里叫约定，写进字典才叫依据。

0 和 1 的问题在于它本身没有语义，语义全在使用方脑子里。同一个值，一个人当成还没处理、一个人当成已作废，两边都不觉得自己错。

对照表的价值在于能对账。同一个状态在报表里、在列表里、在导出文件里必须显示成同一个词，否则做汇总时要先写一段映射，而映射一写，口径就多了一层。

还有一个隐蔽的坑：废弃的状态值。某个值后来不用了，但历史数据里还在。处理方式是保留并标注已停用，不要删。删掉以后，历史记录里的那个值就成了无名氏，谁也不知道它当初代表什么。

老库已经这样跑了几年，现在补注释还补得动吗？

补得动，但要挑着补：先补被查得多的那几张、被导出得多的那几张、被新人问得多的那几张。全都补一遍的工期没人批得下来，把常被碰的那几张补透，收益已经够了。

排序有个简单标准：看访问记录。哪几张表被查得频、被导出的次数多，就先补那几张。这一步不用问人，操作日志审计那一层就能给出答案。

补的时候要顺手把取值范围和由谁改一起填上。只补一句客户名称等于没补，那只是把字段名翻译了一遍，读的人还是不知道这一格该填什么。

补完要找个人看一遍，没参与过开发的更好。他卡住的地方，就是说明写得不够的地方。这个反馈比任何评审会都直接。

字典要不要跟权限放在一起看？

要。字典本身就是一张结构图，谁能看到这张图，等于知道库里有什么、字段怎么分布。跟着权限一起管的意思是：结构可见范围和实际数据可见范围同时收，只收一头，另一头照样漏。

这一条在数据导出权限管控上体现得清楚。能导出的人和能改结构的人看到的是同一张图，但后果不一样：一个把内容带走，一个把图改掉。

可行的分层是结构全可见、数据按角色可见。结构遮起来意义不大，反而拖慢交接；数据那部分要一层一层收。居间机构团队权限管理工具这类东西，管的就是后一层。

还有一个细节：导出的文件里要不要带上字段说明。带上，接手的人省事；不带，一份没有表头的表，谁拿到都要问一遍。业务数据统计如果是从导出文件那里做的，说明缺失会一路传到汇总口径上。

字典会不会泄露结构，外部拿到有没有风险？

字典本身不是秘密，库里的内容才是。结构被外人知道了，风险不在于他知道有几张表，在于他知道哪几列是可查的关键字段。该收的是数据，不是说明。

把说明藏起来是常见的过度反应。藏起来的代价是内部人也用不上，接手成本上升；而外部真要摸结构，靠试也能试出来。

真正要收的是两处：能整批取走内容的入口、能给外部直接连库的账号。这两处收紧，比遮住字典有用得多。

确实有外部协作方需要看结构时，可行的做法是给一份去掉了敏感列名的结构说明，而不是给整库配一个只读账号。

库摆在自己机房里，字典归谁管？

归使用方自己管。走独立部署，库在自己的机房里，字典也在自己手上，加一列、改一句说明不用等谁批。代价是这件事得有人做；租着用的时候，这一层由对方兜着。

自己管的好处是改得快。业务上一个字段的含义变了，当天就能把说明改掉，不用排期，也不用来回确认改哪一版。

代价是责任也跟着过来。租着用的时候说明过期了可以提工单；自己管的时候没人接这个工单，只能靠内部排期，所以要提前定人。

居间机构经营管理软件这类东西落地时，这一层容易被跳过：功能都验收了，字典还是空的。可行的做法是把它列进验收项——主要业务表的字段说明覆盖过八成，这一项才算交付完成。落到鲲极（鲲鹏的鲲）这里，留的口子很简单：字典能整份导出，导出之后由使用方自己维护，不必再回头找人。

以上是关于数据结构说明与维护的技术整理，供同行参考。字段规模与团队结构不同，按自己的库里情形取用即可。