简介：面向医疗信息化开发者与HIS系统实施人员，这份Caché数据库开发文档合集围绕医疗业务场景下的数据存储、接口集成与系统可靠性展开，适合需要从基础环境搭建进阶到高可用设计的初中级技术人员查阅。压缩包共145个文件，以143份PDF文档为主，辅以1个HTML索引页和1张JPG示意图，整体约77.18MB，内容按基础教程、数据模型设计、开发者手册、API参考、高可用与灾难恢复、安全权限管理、报表分析及示例代码等主题组织。已有1034人学习，说明其在HIS开发与Caché技术查阅方面具有一定参考价值。读者可据此了解Caché多维数据模型与MUMPS编程要点，掌握集群部署、权限配置和医疗报表生成等实践思路，并借助示例项目理解Caché与HIS业务模块的衔接方式，为性能优化和故障恢复提供可操作的文档依据。
1. HIS 里为什么还跑着 Caché：一份文档资料能省下的试错成本
门诊高峰期，挂号窗口一秒要落三四个号，后台还得保证号序不重、候诊队列不乱。医院用 Caché 数据库跑 HIS 不是怀旧，它的多维 Global 读写够快、稀疏存储对半结构化的临床数据友好，ObjectScript 直接操作数据节点，少了一层对象关系映射的转换开销。代价是门槛：习惯了关系库的人第一次看到^HIS.OP(...)这种存储结构往往无从下手，碰到锁、事务、索引、CSP 页面报错更难定位。这份 Caché HIS 数据库开发文档资料的价值就在这儿——把 ObjectScript 语法、Global 数据结构、SQL 访问、接口和运维实操摆在一起，新手能照着跑起一套最小环境，熟手能按图索骥改业务模块。
2. 资料包与环境落地：从目录分层到跑起第一个命名空间
拿到一份数据库开发文档，最容易犯的错是从第一页顺序往下读。Caché 这类后关系型数据库，语法手册、SQL 参考、类库 API、HIS 数据字典、运维手册是五种不同用途的材料，混着看只会把概念搅成一锅粥。比较省时间的做法是先按用途拆开，缺什么补什么，剩下的当字典查。
2.1 文档资料的目录分层与阅读顺序
一套完整的 HIS 开发资料通常包含这几块内容：安装部署说明、ObjectScript 与 M 语言语法、SQL 参考（嵌入式 SQL、动态 SQL、视图、存储过程）、类库 API（%Persistent、%SQL.Statement、%CSP.Page等）、HIS 业务表结构与数据字典、接口规范（HL7 v2 消息与 Web Service）、运维手册（备份、日志、镜像、性能诊断）。
| 目录/文档 | 主要内容 | 什么时候翻 |
|---|---|---|
| 安装部署 | 实例安装、字符集、命名空间、Web 网关 | 搭环境当天 |
| 语法手册 | ObjectScript 命令、函数、流程控制 | 写第一个方法 |
| SQL 参考 | 建表、索引、嵌入式/动态 SQL、执行计划 | 做查询和报表 |
| 类库 API | 持久类、流、集合、CSP、安全 | 封装业务层 |
| HIS 数据字典 | Global 节点含义、表字段、字典项 | 对接业务流程 |
| 接口规范 | HL7 段/字段、消息触发事件、返回值约定 | 对接 LIS/PACS/医保 |
| 运维手册 | 备份策略、Journal、镜像切换、日常巡检 | 上线前后 |
阅读顺序建议是：先用安装部署把环境跑起来，翻语法手册写一个能读写的类方法，再对照 HIS 数据字典看真实业务数据落在哪个 Global 节点上。SQL 参考和类库 API 不必通读，做查询时查 SQL，做页面和接口时查类库。运行手册最好在上线前一周过一遍，尤其是备份和日志相关的部分，问题往往出在这里。
提示：数据字典是这套资料里最容易被低估的部分。字段含义、字典项编码、历史数据的兼容说明全在里面，改造前先确认目标字段在字典里的定义，比直接猜 Global 结构靠谱得多。
2.2 部署形态与版本选择：单机、镜像与容器
开发机上一套单机实例足够，生产环境按医院规模选。单机适合小体量门诊，配置简单；镜像（Mirror）适合对可用性有要求的场景，主备自动切换，代价是要多一台机器和一套心跳网络配置；容器化部署近几年用得多了，好处是环境一致、升级回滚快，但要确认数据卷的持久化和 Journal 的落盘位置，否则容器一重建日志就断。
版本上，8.x 系列在 SQL 兼容性、管理门户和 JSON 支持上比老版本完善，新项目可以直接用。老医院现场可能还跑着更早的版本，语法差异主要在 SQL 函数和部分系统类方法名上，改之前先在测试实例验证。安装时字符集一定选 UTF-8，HIS 里的患者姓名、诊断描述、科室名称都是中文，字符集选错后期改代价极高。内存按并发用户数估算，门诊 200 并发以内的开发测试环境给 8GB 能跑，生产环境按实际压力另算。
命名空间（Namespace）是这套体系里的核心隔离单位，一个命名空间对应一套 Global 和 Routine 的映射关系。HIS 项目常见的划分是：业务命名空间放 HIS 主业务，接口命名空间放 HL7 消息和外部系统对接，报表命名空间挂只读映射，避免统计查询拖垮生产库。
2.3 起一套最小可用环境：命名空间、用户与 Web 网关
环境搭起来之后，第一件事不是写业务代码，是把命名空间、用户权限和 Web 应用这三样配通。Caché 的管理操作大多可以在终端里完成，下面是在 Linux 实例上的常用命令。
# 进入实例终端，-U 指定用户，-P 指定密码 csession HIS -U _SYSTEM -P 初始密码 # 终端内切到系统命名空间，创建业务命名空间 %SYS> Do ##class(Config.Namespaces).Create("HIS") # 指定数据库目录创建（可选，默认建在实例的 mgr 目录下） %SYS> Do ##class(Config.Namespaces).Create("HIS","/data/his/") # 给业务命名空间创建 Web 应用，供 CSP 页面访问 %SYS> Do ##class(Security.Applications).Create("/his","HIS") # 查看已创建的命名空间，确认结果 %SYS> Do ##class(Config.Namespaces).List()Create的第一个参数是命名空间名，第二个参数是数据库目录，不传就走默认路径。Web 应用的路径/his是浏览器访问的 URL 前缀，第二个参数指向命名空间，两者对上之后 CSP 页面才能找到对应的类。创建完成后用ZN "HIS"切过去，执行Write $NAMESPACE确认当前命名空间，然后跑一句Write $ZVersion看版本，环境就算通了。
再往下是权限。至少建三类账号：开发账号给%All或开发用的角色，运维账号给备份和监控相关资源，应用连接账号只给业务表和 CSP 页面的访问权限。Caché 的权限模型是资源（Resource）加角色（Role），应用账号不要图省事直接给%All，后期做安全审计时很难收场。
注意：Web 网关（CSP Gateway）和实例是分开部署的，开发机上装在本机没问题，生产环境通常单独一台机器。网关的配置文件里要写清楚实例的 IP、端口和 Web 服务器路径，改完记得重启网关服务，否则页面 404 会让人怀疑人生。
3. 数据模型拆解：Global 多维存储与 HIS 业务表的对应关系
HIS 系统的数据模型有个特点：核心表就那几张，患者主索引、就诊记录、医嘱明细、费用明细，但每张表的下挂数据多、查询维度杂。Caché 用 Global 存这些数据，一个 Global 就是一棵稀疏的多维数组树，下标想怎么排就怎么排。理解这一点，后面看表结构、写查询、调性能都是顺的。
3.1 Global 结构与 HIS 核心表的映射
以门诊业务为例，下面这张表是资料包里数据字典的典型结构，节点名是我按常见命名习惯整理的，实际项目以字典为准。
| Global 节点 | 业务含义 | 下标顺序 | 说明 |
|---|---|---|---|
^HIS.PatientIndexD | 患者主索引 | 内部 ID | 一行一个患者，值用$LISTBUILD存字段 |
^HIS.PatientIndexI | 主索引的索引 | 索引名、键值、ID | 唯一索引和普通索引都在这里 |
^HIS.OP | 门诊就诊记录 | 患者号、就诊号 | 一次就诊一个节点 |
^HIS.ORD | 医嘱明细 | 就诊号、医嘱序号 | 与就诊一对多 |
^HIS.SEQ | 号序/序列 | 业务类型、科室、日期 | $INCREMENT自增用 |
^HIS.LOCK | 业务互斥 | 业务类型、维度 | 不存业务数据，只做锁节点 |
D结尾的是数据节点，I结尾的是索引节点，这是 Caché 持久类默认存储结构的命名习惯。数据节点里一行记录的字段用$LISTBUILD打包成一个列表值，取的时候用$LIST按下标拆。这种存法比一行一个字段的存储紧凑，读写一次到位，代价是可读性差——终端里ZW ^HIS.PatientIndexD(1)看到的是一串$LB值，得对着类定义才知道第几位是什么。
索引节点是编译器自动维护的，不要手工往里写。^HIS.PatientIndexI("PK","P000001",1)=""表示主键索引里登记号为 P000001 的记录内部 ID 是 1。理解这个结构，看执行计划、判断索引是否命中就有依据了。
3.2 ObjectScript 读写：从患者主索引到就诊记录
直接操作 Global 是 Caché 开发的基本功，写起来比 SQL 短，性能也好，适合高频路径。下面这段是患者主索引的写入和读取。
/// 写入患者主索引，patientNo 为登记号 ClassMethod SavePatient(patientNo As %String, name As %String, sex As %String, birthDate As %String) As %Status { // 登记号为空直接拒绝，避免脏数据进主索引 If patientNo = "" Quit $$$ERROR($$$GeneralError, "登记号不能为空") // 用登记号做唯一性判断，已存在则更新，不存在则新增 Set id = $Order(^HIS.PatientIndexI("PK", patientNo, "")) If id = "" { Set id = $Increment(^HIS.PatientIndexD) // 原子自增，多进程安全 } // 字段顺序必须和类定义里的属性顺序一致 Set ^HIS.PatientIndexD(id) = $ListBuild(patientNo, name, sex, $ZDH(birthDate, 3)) Set ^HIS.PatientIndexI("PK", patientNo, id) = "" Set ^HIS.PatientIndexI("NameIdx", name, id) = "" Quit $$$OK } /// 按登记号读取，返回 "姓名^性别^出生日期" ClassMethod GetPatient(patientNo As %String) As %String { Set id = $Order(^HIS.PatientIndexI("PK", patientNo, "")) If id = "" Quit "" Set data = $Get(^HIS.PatientIndexD(id)) Quit $List(data, 2) _ "^" _ $List(data, 3) _ "^" _ $ZD($List(data, 4), 3) }$Increment是这段代码里最关键的一个函数，它对指定节点做原子加一，多个进程同时调用也不会拿到重复值，号序、流水号、主键生成都靠它。用Set ^X = $Get(^X) + 1替代会丢号、重号，这是血泪经验。$ZDH和$ZD负责日期和 Caché 内部日期格式（从 1840 年 12 月 31 日起算的天数）之间的转换，3表示输出YYYY-MM-DD格式。$List(data, 2)取列表第 2 个元素，下标从 1 开始。
$Order的用法要留意：$Order(^GLO(sub, key, ""))返回该下标下的下一个值，找不到返回空串。上面用它查唯一索引，命中就返回内部 ID，没命中就是空。这种写法在判断存在性时比$Data更直接，因为索引节点是三级结构，$Data只能告诉你有没有，拿不到 ID。
3.3 SQL 访问层：嵌入式 SQL、动态 SQL 与视图
Caché 同时支持关系视图，同一份数据既能用 Global 操作，也能用 SQL 查。对外提供报表、给第三方系统做只读查询、写复杂关联统计，用 SQL 更省事。两种写法按场景选：高频单条读写走 Global，多表关联和汇总走 SQL。
嵌入式 SQL 在编译期就确定语句，性能好，适合固定查询。
/// 按登记号查患者，返回状态码和拼接结果 ClassMethod GetPatientBySQL(patientNo As %String) As %String { Set name = "", sex = "", birthDate = "" &sql( SELECT Name, Sex, BirthDate INTO :name, :sex, :birthDate FROM HIS.PatientIndex WHERE PatientNo = :patientNo ) If SQLCODE = 0 { Quit name _ "^" _ sex _ "^" _ $ZD(birthDate, 3) } ElseIf SQLCODE = 100 { Quit "" // 100 表示没有查到记录 } Else { Quit "ERR^" _ %msg } }&sql(...)里的:变量是宿主变量，执行结果直接回填。SQLCODE是要重点记的：0 成功，100 无数据，负数出错；正数在部分语句里表示影响行数，别一律当成功处理。%msg带的是错误描述，日志里打出来定位问题比只打 SQLCODE 快得多。
动态 SQL 适合条件不固定的查询，比如带多个可选筛选项的检索页面。
/// 动态 SQL 分页查询，page 从 1 开始 ClassMethod QueryPatient(name As %String, page As %Integer, pageSize As %Integer) As %SQL.StatementResult { Set stmt = ##class(%SQL.Statement).%New() Set stmt.%SelectMode = 2 // 拼接条件时只拼 SQL 结构，值一律走参数，避免注入 Set sql = "SELECT PatientNo,Name,Sex FROM HIS.PatientIndex WHERE 1=1" If name '= "" Set sql = sql _ " AND Name %STARTSWITH ?" Set sc = stmt.%Prepare(sql) If $$$ISERR(sc) Quit $$$NULLOREF If name '= "" { Set rs = stmt.%Execute(name, (page - 1) * pageSize + 1, pageSize) } Else { Set rs = stmt.%Execute((page - 1) * pageSize + 1, pageSize) } Quit rs }%Prepare做语法检查和执行计划缓存，%Execute传参执行。%SelectMode = 2让日期以逻辑值返回，前端再格式化，避免服务端时区问题。结果集用While rs.%Next() { ... }遍历，字段用rs.PatientNo取。分页这里用%Execute的参数占位，实际项目里 TOP 和 OFFSET 的写法在不同版本上兼容性有差异，上线前在目标版本上验证一遍。
视图的作用是把 Global 结构翻译成业务方看得懂的表名。CREATE VIEW把多个 Global 节点关联成一张宽表，第三方系统只认表名和字段名，不关心底下是 Global 还是表。视图定义改起来比改接口协议便宜，算是一层解耦。
3.4 类定义与持久化：把表结构写成类
Caché 的推荐做法是用持久类定义数据结构，编译时自动生成 Global 存储和 SQL 表，索引、约束、默认值都在类定义里声明，比手工维护 Global 结构靠谱。
Class HIS.PatientIndex Extends %Persistent { Property PatientNo As %String(MAXLEN = 20) [ Required ]; Property Name As %String(MAXLEN = 50); Property Sex As %String(MAXLEN = 4); Property BirthDate As %Date; Property IdCard As %String(MAXLEN = 18); Index PK On PatientNo [ Unique ]; Index NameIdx On Name; Index BirthIdx On BirthDate; }属性类型决定存储和校验：%String(MAXLEN=...)限长，%Date走日期转换，Required在保存时强制非空。索引声明成Unique后，插入重复登记号会返回错误而不是静默覆盖，这个约束在患者主索引上必须有。Storage块不用手写，在 IDE 里编译时选生成存储即可，它会按属性顺序生成$ListBuild的节点结构。
类定义和 Global 操作不是二选一，实际项目里常常混用：业务写入走类方法，保证索引和约束生效；高频只读路径直接读 Global，绕开对象层。混用要注意一点——手工写 Global 时必须同步维护索引节点，否则 SQL 查出来的结果和 Global 对不上，这类问题排查起来非常费劲。
4. 接口与业务链路：门诊挂号到医嘱执行的完整走查
光有表结构不够，HIS 的复杂度在链路上。一个门诊患者从挂号到开单、缴费、执行，跨好几个模块，中间还夹着外部系统的消息。这一章按调用顺序走一遍，重点看代码怎么落、数据怎么流。
4.1 CSP 页面与后端方法的调用链
Caché 自带 CSP（Caché Server Pages）做 Web 页面，.csp文件或继承%CSP.Page的类都能当页面入口。HIS 的门诊挂号界面很多是这种结构：页面负责渲染，后端类方法负责取数据和写数据。
Class HIS.Web.RegPage Extends %CSP.Page { Parameter CONTENTTYPE = "text/html"; ClassMethod OnPage() As %Status { &html<<html><head><meta charset="utf-8"><title>门诊挂号</title></head><body>> &html<<h3>今日号源</h3>> // 查当天各科室剩余号源，rs 为结果集 Set rs = ##class(%SQL.Statement).%ExecDirect(, "SELECT DeptCode,DeptName,Total - Used AS Remain FROM HIS.Schedule WHERE WorkDate = CURRENT_DATE") &html<<table border="1">> While rs.%Next() { Write "<tr><td>"_rs.DeptCode_"</td><td>"_rs.DeptName_"</td><td>"_rs.Remain_"</td></tr>" } &html<</table></body></html>> Quit $$$OK } /// 页面提交的挂号动作，参数由前端表单传入 ClassMethod Reg(patientNo As %String, deptCode As %String) As %String { If patientNo = "" Quit "ERR^患者登记号为空" If deptCode = "" Quit "ERR^科室编码为空" // 真正的写号逻辑在业务类里，页面只做参数校验和结果回显 Quit ##class(HIS.BO.Register).CreateVisit(patientNo, deptCode) } }&html<>块里只能写 HTML，ObjectScript 语句要放在块外，这是 CSP 的硬规则，写错了编译直接报错。OnPage是页面渲染入口，返回$$$OK表示正常。页面里的数据查询用%ExecDirect一行搞定，适合简单查询；复杂的建议放到独立的业务类里，页面只负责展示。
Reg这个类方法是通过 AJAX 或表单提交调用的，参数从请求里取。实际项目里这一层还要做登录态校验和权限判断，资料包里的示例往往省略了，直接拿去用会留安全口子。
4.2 HL7 消息接入与落库
医院里 HIS 和 LIS、PACS、医保、区域平台对接，HL7 v2 是绕不开的。一条 ADT 消息进来，先按段拆，再按字段取值，最后落到患者主索引和就诊记录里。
/// 解析 ADT 消息并写入主索引，msg 为完整消息文本，段之间用回车分隔 ClassMethod ImportADT(msg As %String) As %Status { Set segCount = $Length(msg, $Char(13)) Set patientNo = "", name = "", visitNo = "", deptCode = "" For i = 1:1:segCount { Set seg = $Piece(msg, $Char(13), i) Set segName = $Piece(seg, "|", 1) If segName = "PID" { // PID-3 患者标识，PID-5 姓名（姓^名） Set patientNo = $Piece(seg, "|", 4) Set name = $Piece($Piece(seg, "|", 6), "^", 1) } If segName = "PV1" { // PV1-2 患者类型，PV1-3 所在科室，PV1-19 就诊号 Set deptCode = $Piece($Piece(seg, "|", 4), "^", 1) Set visitNo = $Piece(seg, "|", 20) } } If patientNo = "" Quit $$$ERROR($$$GeneralError, "PID 段缺少患者标识") // 先落主索引，再落就诊记录，保证外键关系成立 Do ##class(HIS.PatientIndex).SavePatient(patientNo, name, "", "") If visitNo '= "" { Set ^HIS.OP(patientNo, visitNo) = $ListBuild(deptCode, "", $ZDT($Horolog, 3), "0") } Quit $$$OK }$Length(msg, $Char(13))按回车符统计段数，HL7 v2 的段分隔符就是回车（部分系统用\r\n，接入前先确认发送方用的是哪种）。$Piece(seg, "|", 4)取第 4 个字段，因为第 1 个是段名，所以 PID-3 对应下标 4。复合字段再用^拆一层，比如姓名是姓^名^中间名。
这段代码有两个实际项目里必须补的点：一是消息要落原始报文表，出问题能回放；二是落库要做幂等，同一条消息重复推送不能产生重复就诊记录。资料包里的示例通常只演示解析，幂等和回放要自己加。
4.3 事务、锁与并发挂号抢号
挂号是并发最集中的场景，同一个科室同一天的号序必须唯一。Caché 的锁是显式的，Lock加锁、$Test判断是否拿到、用完必须释放；事务用TSTART/TCOMMIT/TROLLBACK。
/// 创建就诊记录，返回就诊号；抢号失败返回 BUSY ClassMethod CreateVisit(patientNo As %String, deptCode As %String) As %String { // 锁粒度到 科室+日期，锁超时 5 秒，避免无限等待 Lock +^HIS.LOCK("REG", deptCode, +$Horolog):5 If '$Test Quit "BUSY" Set visitNo = "" Try { TSTART // 号序用 $Increment 原子自增，天然不会重号 Set seq = $Increment(^HIS.SEQ("REG", deptCode, +$Horolog)) Set visitNo = deptCode _ $ZD(+$Horolog, 8) _ $Translate($Justify(seq, 4), " ", "0") Set ^HIS.OP(patientNo, visitNo) = $ListBuild(deptCode, "", $ZDT($Horolog, 3), "0") Set ^HIS.SEQINDEX(visitNo) = patientNo TCOMMIT } Catch ex { TROLLBACK Set visitNo = "" Do ##class(%Exception.Log).Log(ex) } Lock -^HIS.LOCK("REG", deptCode, +$Horolog) Quit visitNo }锁的写法是Lock +节点:超时秒数，加锁后$Test为 1 表示成功。锁节点本身不存数据，只做互斥标记，所以放在^HIS.LOCK下和业务数据分开。+$Horolog把日期转成数字做下标，比字符串日期省空间。
$Increment在这里承担了号序生成的职责，但要注意它和事务的关系：$Increment是立即生效的，事务回滚不会把序号退回去，所以会出现号序不连续。医院业务上一般不要求连续，只要求唯一，如果确实要求连续，就得换成锁内查询最大值再写的方案，性能会差一截。
$Justify(seq, 4)右对齐补空格，再用$Translate把空格换成 0，拼出定长的流水号。这种字符串处理在 Caché 里很常见，函数组合起来用比写循环快。
4.4 报表与统计查询：从 Global 到统计查询
门诊量统计、科室收入、医生工作量，这类查询用 SQL 写比遍历 Global 直观。前提是索引建对。
-- 按科室统计指定日期区间的就诊人次 SELECT DeptCode, COUNT(*) AS Cnt FROM HIS.OPVisit WHERE VisitDate BETWEEN :startDate AND :endDate GROUP BY DeptCode ORDER BY Cnt DESC这段 SQL 能不能跑快，取决于VisitDate和DeptCode上有没有合适的索引。Caché 支持位图索引（bitmap index），适合低基数列，比如科室编码、性别、状态这类取值不多的字段，统计查询走位图索引比普通索引快一个量级。在类定义里声明：
Index DeptDateIdx On (DeptCode, VisitDate) [ Type = bitmap ];复合位图索引的列顺序有讲究：把选择性低、过滤条件常用的列放前面。科室在前、日期在后，适合先按科室圈定范围再过滤日期；反过来如果查询总是先按日期筛全天数据，就把日期放前面。建完索引记得重新收集统计信息，否则优化器还是按旧数据选计划。
执行计划怎么看：在管理门户的 SQL 执行界面执行语句后点 Show Plan，或者用%SQL.Statement的%DisplayPlan()方法。计划里出现Master Map全表扫描就是没走索引，先查索引定义，再查统计信息是否过期。
5. 避坑与排查：Caché + HIS 场景下最常见的几类翻车
这套组合的坑有个共同点：开发环境一切正常，上线后才暴露。原因要么是数据量差了几个数量级，要么是并发和权限在开发机上根本模拟不出来。下面几条是我在实际项目里踩过的，按现象、原因、解决三段写，遇到类似症状可以对着排查。
5.1 数据与并发类问题
现象：同一天同一科室出现两个相同的就诊号，护士站叫号叫重了。
原因：号序生成用了Set ^HIS.SEQ(...) = $Get(^HIS.SEQ(...)) + 1这种非原子写法，两个进程同时读到同一个值再各自加一，结果撞号。开发机上单用户测试永远发现不了。
解决：号序统一换成$Increment，它是数据库层面的原子操作，多进程并发也不会重复。业务上如果还要求号段连续，就在$Increment外面再套一层科室级锁，把“取号+写记录”放在同一个临界区里，锁超时要设，不能无限等。
现象：SQL 查出来的患者数量和界面显示的对不上，少了几条。
原因：手工写 Global 时只写了数据节点^HIS.PatientIndexD，没有同步维护索引节点^HIS.PatientIndexI，SQL 走索引查，自然漏数据。反过来只写索引不写数据节点，就会出现“查得到但取不出详情”的幽灵记录。
解决：业务写入一律走持久类的%Save()方法，让编译器维护索引；确实要手工写 Global 的高频路径，写完必须补索引节点，并且加一个定时校验任务，比对数据节点和索引节点的数量差，差值为 0 才放心。
现象：报表查询跑了三十秒还没出结果，数据库 CPU 打满。
原因：统计 SQL 的过滤字段上没有索引，或者索引建了但统计信息是空的，优化器选不到索引，走了全表扫描。数据量小的时候看不出来，几十万行之后就原形毕露。
解决：先看执行计划确认是否走索引，再补索引或调整复合索引的列顺序。建完索引执行统计信息收集，让优化器拿到真实的数据分布。报表类查询尽量走只读的报表命名空间，用映射挂生产库的 Global，避免大查询直接压在生产实例上。
5.2 部署与运维类问题
现象：CSP 页面本地能打开，部署到另一台机器上返回 404。
原因：Web 网关的配置和实例的 Web 应用路径没对上。本地开发时网关和实例装在同一台机器，路径默认匹配；换机器后网关配置里还是旧的 IP 和端口，或者 Web 应用路径的大小写、结尾斜杠不一致。
解决：对照管理门户里的 Web Applications 配置，逐项核对路径、命名空间、物理文件目录。网关配置文件改完必须重启网关服务，只重启实例没用。路径匹配是精确匹配，/his和/his/在后端可能被当成两个应用，这点容易被忽略。
现象：数据库文件持续增长，但业务量没涨，磁盘告警。
原因：Journal 日志没有配置自动清理，或者备份留下的旧文件没删。另一个常见原因是废弃的临时 Global 没人清理，比如调试时写的^TMP、^TEST节点一直挂着。
解决：检查 Journal 的保留策略，按恢复窗口设置保留天数；备份任务加上清理旧备份的步骤；定期用^%GSIZE看各 Global 的实际占用，找出异常大的节点。清理前先确认不是业务数据，删 Global 是不可逆操作，生产环境先做备份。
现象：中文显示成乱码，或者部分生僻字变成问号。
原因：实例安装时字符集选错，或者终端客户端的字符集和实例不一致。Caché 的字符串在 UTF-8 下是变长存储，老版本用单字节字符集时截断规则不同，迁移数据时如果没做转换，字段长度会算错。
解决：新装实例一律选 UTF-8，迁移前在测试环境跑一遍全量数据校验，重点看%String字段的MAXLEN是按字符算还是按字节算。终端乱码多半是客户端设置问题，改成 UTF-8 编码重连即可。
6. 二次开发：在现有文档与代码上做增量改造
拿到一份 HIS 的开发资料，真正要动手时，八成是加功能而不是重写。新增一张业务表（比如随访记录）的完整路径是这样的：先在类定义里声明属性和索引，编译生成存储和 SQL 表；再写业务类方法，封装增删改查；然后挂到 CSP 页面或接口上；最后补权限和字典项。
Class HIS.FollowUp Extends %Persistent { Property PatientNo As %String(MAXLEN = 20) [ Required ]; Property VisitNo As %String(MAXLEN = 30); Property FollowDate As %Date; Property Content As %String(MAXLEN = 500); Property Status As %String(MAXLEN = 4) [ InitialExpression = "0" ]; Index PatientIdx On PatientNo; Index DateIdx On FollowDate; }InitialExpression给状态字段一个默认值，省得每个调用方都记得传。索引按查询场景建，患者号和日期是随访查询的两个主要入口，各建一个，不要图省事建一堆用不上的索引，写入会变慢。
改完之后的验证，我一般走这几步，缺一步都不敢上线。
| 验证项 | 怎么做 | 通过标准 |
|---|---|---|
| 编译 | 在目标命名空间编译类，看错误列表 | 零错误零警告 |
| 存储结构 | 插一条测试数据，ZW看 Global 节点 | 字段顺序与类定义一致 |
| SQL 可见性 | 用 SQL 查新建的表 | 能查到刚插的数据，索引字段可过滤 |
| 权限 | 用应用账号登录执行 | 该有的能访问，不该有的报权限错误 |
| 并发 | 多进程同时写号序 | 无重号、无死锁报错 |
| 回滚 | 事务中途抛异常 | 数据不残留，号序可接受不连续 |
有一点我吃过亏：测试环境验证通过不代表生产没问题，两边数据量差两个数量级时，执行计划会变。所以每次改完索引相关的逻辑，我都会在接近生产数据量的库上再跑一遍执行计划，确认没走全表扫描才放心。
从那以后，我每次拿到一份数据库开发文档，第一件事不是读语法，而是先照着安装章节把环境跑起来，再对着数据字典找到第一个业务 Global 节点，用ZW看一眼真实结构——看懂了结构，后面的代码和文档才接得上。希望帮到你。
本文还有配套的精品资源，点击获取
