---
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")`
- **前后端同时使用**：两个注解同时使用确保兼容性
- **前端显示格式化**：解析字符串日期并格式化为所需格式

### 示例代码
```java
@DateTimeFormat(pattern = "yyyy-MM-dd")
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date planTimeStart;
```

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

## 2. 前端国际化配置

### 问题类型
- 组件库默认语言为英文
- 日期控件显示语言不符

### 解决方案
- 在main.js中引入语言包
- 配置Element Plus使用中文语言环境

### 示例代码
```javascript
import zhCn from 'element-plus/es/locale/lang/zh-cn'

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

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

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

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

### 示例代码
```java
@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
- 只对同时存在于两库的表使用分离
- 正确配置默认数据源

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

## 5. 前端组件优化

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

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

### 示例代码
```html
<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. **统一组件封装**：创建可复用的防重复点击组件

### 示例代码
```vue
<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应用问题、处理日期时间、配置数据源、优化前端组件时使用此技能。