---

name: sankhya-dashboard-html-jsp-custom-best-pratices description: "当用户询问 Sankhya 仪表盘（使用 HTML、JSP、Java 和 SQL）的模式、最佳实践、创建或修复时，应使用此技能。" category: code risk: safe source: community tags: [sankhya, dashboard, jsp, html, sql, best-practices] date_added: "2026-03-10"

Sankhya 仪表盘 HTML/JSP 自定义最佳实践

用途

提供一份关于在 Sankhya 生态系统（JSP/HTML/Java）中创建和维护仪表盘、SQL 查询、BI 参数化以及 UI/UX 的模式和最佳实践综合指南。

何时使用此技能

此技能适用于以下场景：

• 用户询问"Sankhya 最佳实践"相关内容。
• 用户提到"Sankhya 仪表盘"或正在开发 Sankhya BI 仪表盘。
• 用户询问任何与"Sankhya"相关的内容。
• 用户想要创建或修改 Sankhya 仪表盘的代码文件。

核心能力

1. 代码生成与审查：应用 JSP/JSTL 模式和服务端组织方式，减少编译错误和渲染失败。
2. 视觉一致性：使用预定义的 CSS 令牌标准化 BI 组件的视觉标识。
3. 数据库探索：构建高性能的数据探索查询，正确映射 Sankhya 实体。
4. BI 构建指南：使用 BI 中的 HTML5 组件流程，确保正确的渲染、响应性和导航。

模式

代码最佳实践

应用 JSP/JSTL 模式和服务端组织方式，减少仪表盘/页面中的编译错误、渲染失败和回归问题。

实施准则

• 在文件顶部声明必需的 JSP 指令和标签库。
• 强制设置 isELIgnored="false" 以在渲染时启用 ${...} 表达式。
• 在 Sankhya 生态系统中优先使用 core_rt 作为 JSTL core。
• 避免在 JSP 中使用 Java scriptlet；使用 JSTL（c:if、c:choose、c:forEach）。
• 模块化业务逻辑（分层/服务），避免单文件耦合。
• 避免硬编码凭据、敏感 URL 和令牌。
• 建模 UI 全局状态（数据、筛选器、排序、活动标签页），在新加载前重置状态。
• 将可视化偏好持久化到 localStorage（列顺序和排序）。
• 对重型标签页/模态框实施按需加载（懒加载），减少初始加载时间。
• 参数防护：始终通过 c:set 为 URL 参数定义默认值（回退值），避免 Sankhya Java 服务器出现 500 错误。
• 层分离（JSP vs JS）：避免在 <script> 块中直接注入 JSP 标签。使用隐藏的 HTML 容器向 JavaScript 传递数据，保持代码编辑器（IDE Linting）的健康。

以下表名和字段名仅为示例，可能因实例实现而异。

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="snk" uri="/WEB-INF/tld/sankhyaUtil.tld" %>
<%@ taglib uri="http://java.sun.com/jstl/core_rt" prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
<snk:load />

仪表盘/小组件中的资源加载

• 使用 contextPath + BASE_FOLDER 引用文件。
• 在二级层级（openLevel）中，保持绝对路径以避免解析中断。

<script src="${pageContext.request.contextPath}/${BASE_FOLDER}/js/app.js"></script>
<link rel="stylesheet" href="${pageContext.request.contextPath}/${BASE_FOLDER}/css/style.css" />

安全使用 snk:query

• 遍历 query.rows（而非根对象）。
• 使用 empty query.rows 测试空值。

<snk:query var="qDados">
    SELECT CAB.NUNOTA, CAB.CODPARC
      FROM TGFCAB CAB
</snk:query>

<c:choose>
    <c:when test="${empty qDados.rows}">
        <span>无结果</span>
    </c:when>
    <c:otherwise>
        <c:forEach var="linha" items="${qDados.rows}">
            ${linha.NUNOTA}
        </c:forEach>
    </c:otherwise>
</c:choose>

SQL 注入前的参数清理

• 规范化输入值。
• 在注入查询前移除引号（" 和 "）。
• 定义安全回退值以避免无效 SQL。

<c:set var="raw_codusu" value="${empty param.P_CODUSU ? '0' : param.P_CODUSU}" />
<c:set var="codusu_limpo" value="${fn:replace(raw_codusu, '\"', '')}" />
<c:set var="codusu_limpo" value="${fn:replace(codusu_limpo, '&quot;', '')}" />
<c:set var="codusu_seguro" value="${empty codusu_limpo ? '0' : codusu_limpo}" />

<snk:query var="qAcessos">
    SELECT CODUSU, NOMEUSU
      FROM TSIUSU
     WHERE CODUSU = :codusu_seguro
</snk:query>

页面状态与单仪表盘中的懒加载

• 定义全局列表以在 KPI、图表、表格和模态框中复用。
• 为每个标签页保存加载标志，避免不必要的重复查询。
• 在筛选器变更时从数据源重新加载。