TugboatAIRebuild/.trae/skills/web-dev-best-practices/SKILL.md

---

name: "web-dev-best-practices"

description: "Provides best practices for web development including date handling, internationalization, pagination, and data source configuration. Invoke when developing new pages or troubleshooting common web app issues."

Web开发最佳实践指南

1. 时间日期处理最佳实践

问题类型

• 前端日期字符串与后端Date对象转换问题
• GET请求参数中的日期格式处理
• JSON序列化中的日期格式处理
• 前端显示的日期格式化

解决方案

• 后端接收GET参数：使用 @DateTimeFormat(pattern = "yyyy-MM-dd")
• 后端JSON序列化：使用 @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
• 前后端同时使用：两个注解同时使用确保兼容性
• 前端显示格式化：解析字符串日期并格式化为所需格式

示例代码

@DateTimeFormat(pattern = "yyyy-MM-dd")
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date planTimeStart;

// 前端日期解析和格式化
const parsedDate = new Date(dateString);
if (!isNaN(parsedDate.getTime())) {
  // 格式化为所需格式
  return `${year}-${month}-${day} ${hours}:${minutes}`;
}

2. 前端国际化配置

问题类型

• 组件库默认语言为英文
• 日期控件显示语言不符

解决方案

• 在main.js中引入语言包
• 配置Element Plus使用中文语言环境

示例代码

import zhCn from 'element-plus/es/locale/lang/zh-cn'

app.use(ElementPlus, {
  locale: zhCn
})

3. 搜索和分页功能最佳实践

问题类型

• 搜索和列表功能分离
• 大数据量性能问题
• 用户体验不佳

解决方案

• 合并搜索和列表功能，通过参数判断
• 实现数据库分页，减少内存占用
• 添加瀑布流加载，提升用户体验
• 使用 COALESCE 函数处理空值判断

示例代码

@Query("SELECT new com.example.dto(...) " +
       "FROM ... " +
       "WHERE ... AND (COALESCE(:query, '') = '' OR ...) ")
Page<SearchResult> searchWithPage(@Param("query") String query, Pageable pageable);

4. 数据库读写分离和数据源配置

问题类型

• 误解数据库架构
• 错误的数据源配置
• 混淆读写分离概念

解决方案

• 明确区分两种数据库类型：
  • tugboatcommon：系统公共库，存储所有机构共享数据
  • liandatugboatmis：分支机构业务库，存储各机构业务数据
• 使用有意义的命名而非READ/WRITE：
  • COMMON → tugboatcommon
  • BRANCH → liandatugboatmis
• 只对同时存在于两库的表使用分离
• 正确配置默认数据源

示例代码

public enum DataSourceType {
    COMMON("common"),      // tugboatcommon: 系统公共库
    BRANCH("branch");     // liandatugboatmis: 分支机构业务库
}

5. 前端组件优化

问题类型

• 下拉选择器性能问题
• 数据显示字段错误
• 用户交互体验差

解决方案

• 实现虚拟滚动或分页加载
• 明确显示字段与值字段的区别
• 添加加载状态提示
• 实现滚动加载更多功能

示例代码

<el-select
  v-model="value"
  filterable
  remote
  popper-class="custom-popper"
  :remote-method="searchMethod">
  <div v-if="loadingMore" class="loading">加载中...</div>
  <el-option
    v-for="item in options"
    :key="item.id"
    :label="item.displayField"  <!-- 显示字段 -->
    :value="item.valueField">   <!-- 值字段 -->
  </el-option>
</el-select>

6. 调试和开发流程

最佳实践

• 针对性启动：修改哪个项目就重新调试哪个项目，不要每次都全部重启
• 渐进式开发：先实现基础功能，再逐步优化
• 前后端分离调试：分别启动前后端服务进行调试
• 日志监控：关注错误信息和警告信息
• 版本控制：及时保存中间状态，避免丢失重要修改

7. 前端防重复点击最佳实践

问题类型

• 用户快速多次点击按钮或触发异步操作
• 多次发送相同请求
• 数据重复提交
• 用户体验不佳
• 系统资源浪费

解决方案

在所有触发后台操作的前端事件中添加进度条和防重复点击机制。

实现方法

1. 使用loading状态控制：在按钮上绑定loading属性，在请求期间禁用按钮
2. 全局Loading覆盖：对于页面级别的操作，使用全局Loading遮罩
3. 防抖和节流技术：对于频繁触发的操作，使用debounce或throttle
4. 统一组件封装：创建可复用的防重复点击组件

示例代码

<template>
  <el-button 
    :loading="loading" 
    @click="handleAction"
    :disabled="loading">
    {{ loading ? '处理中...' : '提交' }}
  </el-button>
</template>

<script>
export default {
  data() {
    return {
      loading: false
    }
  },
  methods: {
    async handleAction() {
      if (this.loading) return; // 防止重复点击
      
      this.loading = true;
      try {
        // 执行后台操作
        await this.apiCall();
      } finally {
        this.loading = false; // 确保无论成功失败都恢复状态
      }
    }
  }
}
</script>

8. 常见陷阱和注意事项

1. 注解使用场景：

   • @DateTimeFormat 用于请求参数绑定
   • @JsonFormat 用于JSON序列化/反序列化

2. 命名规范：

   • 避免使用可能引起误解的命名（如READ/WRITE）
   • 使用业务含义明确的命名

3. 数据一致性：

   • 确保前后端日期格式一致
   • 保证显示字段与业务需求一致

4. 性能考虑：

   • 大数据量时使用分页
   • 合理使用缓存
   • 避免不必要的数据传输

使用时机

在开发新页面功能、调试常见Web应用问题、处理日期时间、配置数据源、优化前端组件时使用此技能。