在前端开发中，状态管理是构建复杂应用的核心能力之一，而React作为主流框架，它提供了多种状态管理方案.

然而，随着应用规模扩大，组件层级加深，传统的状态传递方式似乎优点捉襟见肘了，于是，为了解决这种问题，useReducer和useContext诞生了。

今天，我将从组件通信的不足开始，逐渐深入地讲解如何通过useReducer实现高效、可维护的全局状态管理。

一、组件通信简单介绍

1.1 组件通信的常见方式：

• 父子组件通信：通过props传递数据，子组件通过props接收父组件的数据。


• 子父组件通信：子组件通过props传递回调函数（自定义事件）给父组件，实现数据反向传递。


• 兄弟组件通信：通过父组件作为中间人进行传递数据。


• 跨层级通信：使用useContext创建共享上下文（Context），直接跨层级传递状态，详细讲解可以看我之前的文章《useContext : hook中跨层级通信的优雅方案》。

1.2 Context 的不足：

然而，尽管useContext解决了跨层级传递状态的问题，避免了数据臃肿，但是，它在以下场景中仍存在一些缺陷：

• 当Context频繁更新时，所有依赖该Context的组件都会重新渲染，即使某些组件并未使用更新后的数据，容易导致性能问题。


• Context能解决标签的跨级传输，然而，多个Context嵌套也会导致组件层级臃肿（比如<LoginContext.Provider>中包裹<ThemeContext.Provider>）。


• Context本身只提供数据共享能力，它并不涉及到状态更新逻辑，需结合useState或useReducer使用，这就导致了状态管理分散问题。

因此，当应用状态逻辑变得复杂、需集中管理时，useReducer就成为了更优的选择。

二、useReducer详解

2.1 useReducer的定义与作用

useReducer，响应式状态管理，它是React提供的用于管理复杂状态逻辑的Hook。

useReducer通过将状态（state）交由一个纯函数（reducer）进行统一管理，并通过派发动作（dispatch action）触发状态更新，而非直接修改状态。

2.2 useReducer的参数与返回值

const [state, dispatch] = useReducer(reducer, initialState);

• 参数1：reducer函数：根据当前状态和传入的action，返回新的状态。


• 参数2：initialState：初始状态对象。


• 返回值：
  
  
  
  
  • state：表示当前状态值。
  
  
  • dispatch：用于触发状态更新的函数，接受一个action对象作为参数。
  
  
  
  

2.3 纯函数（Pure Function）

useReducer的参数里面，其中，要求reducer函数必须是一个纯函数。

纯函数的特性：

举个例子：

// 不纯的函数

let total = 0;

function addToTotal(a) {

  total += a; // 修改了外部变量

  return total;

}



// 纯函数

function reducer(state, action) {

  switch (action.type) {

    case 'increment':

      return { count: state.count + 1 }; // 返回新对象

    default:

      return state;

  }

}

代码功能说明：

• addToTotal函数直接修改了外部变量total，导致结果不可预测。


• 而reducer函数通过返回新对象的方式更新状态，符合纯函数的要求。

三、用计数器案例讲解useReducer

3.1 代码实现的功能

以下代码实现了一个计数器功能，它通过按钮点击+1或-1修改Count值，输入自定义数值后，通过+???按钮，将该数值加到Count上。

效果如下：

关键代码片段：

import { useState,useReducer } from 'react'

import './App.css'



const initialState ={

  count :0,

}

//关键代码

const reducer = (state ,action)=>{

  switch(action.type){

    case 'increment':

    return {

      count:state.count +1

    };

    case 'decrement':

    return { 

      count:state.count -1

    };

    case 'incrementByNum':

      return{

        count:state.count +parseFloat(action.payload)

      }

    default:

      return state

  }

}



function App(){

const [count ,setCount] = useState(0)

const [state, dispatch]= useReducer(reducer, initialState)



  return (

    <>

      <p>Count:{state.count}</p>

      <input type="text" value={count} onChange={(e)=>setCount(e.target.value)}/>

      <button onClick={()=>dispatch({type:'increment'})}> +1 </button>

      <button onClick={()=>dispatch({type:'decrement'})}> -1</button>

      <button onClick={()=>dispatch({type:'incrementByNum',payload:count})}> +??? </button>

    </>

  )

}

export default App

3.2 代码讲解：

• 在第9行中，reducer函数通过switch语句处理三种类型的action即当触发increment、decrement、incrementByNum行为时，分别返回不同的新的状态对象。


• 而dispatch函数用于触发状态更新，例如第35行，dispatch({ type: 'increment' })函数会在我们触发increment行为时，将计数器值增加1。


• 用户可以通过输入框输入自定义数值，并通过incrementByNum操作将其加到当前计数器上。

关键部分：

四、总结

4.1 useReducer的适用场景

• 复杂状态逻辑：当状态更新逻辑涉及多个条件分支或嵌套结构时（如计数器的incrementByNum操作）。


• 集中管理状态：通过将状态更新规则统一到reducer中，避免分散在多个组件或回调函数中。

4.2 实际应用建议

• 结合useContext：通过useContext创建共享状态，useReducer管理状态更新，形成轻量级全局状态管理方案。


• 模块化设计：将不同功能的reducer拆分为独立文件（如counterReducer.js、formReducer.js），提升代码可维护性。

在上一章 过滤器策略 (FilterPolicy) 中，我们学习了 LevelDB 如何利用布隆过滤器这样的巧妙设计，在访问磁盘前就过滤掉大量不存在的键查询，从而避免了无谓的 I/O 操作。

至此，我们已经探索了 LevelDB 从用户接口到底层数据结构，再到性能优化的几乎所有核心组件。但我们忽略了一个最基础的问题：LevelDB 是一个 C++ 库，它需要运行在真实的操作系统上。它是如何在不同的操作系统（如 Linux, Windows, macOS）上读写文件、创建线程、获取当前时间的呢？难道 LevelDB 的核心代码里充斥着大量的 #ifdef __linux__ 和 #ifdef _WIN32 这样的条件编译指令吗？

如果真是这样，代码将会变得难以维护，移植到新平台也会是一场噩梦。为了优雅地解决这个问题，LevelDB 引入了它的基石——环境（Env）。

什么是环境 (Env)？

Env 是对操作系统底层功能的一个抽象层。你可以把它想象成一个万能工具箱。LevelDB 的核心逻辑（比如 合并 (Compaction) 线程、排序字符串表 (SSTable) 的读写）在工作时，并不直接调用操作系统的原生函数（如 open, read, CreateFileW），而是从这个标准的“工具箱”里取工具来用。

这个工具箱里有什么呢？它定义了一套标准的工具接口：

• NewWritableFile(...): 给我一把能写文件的“扳手”。


• StartThread(...): 给我一个能启动新线程的“马达”。


• NowMicros(): 给我一个能读取当前微秒时间的“秒表”。


• SleepForMicroseconds(...): 让我休息一下的“闹钟”。

有了这个标准的工具箱接口，LevelDB 的核心逻辑就可以完全不关心自己到底运行在哪个操作系统上。它只管向 Env 索要工具。

那么，具体的工具是从哪里来的呢？LevelDB 为每个它支持的平台，都提供了一个具体的工具箱实现。

• 在 Linux/macOS (POSIX) 上，它提供一个 PosixEnv。这个工具箱里的“扳手”是用 open() 和 write() 实现的。


• 在 Windows 上，它提供一个 WindowsEnv。这个工具箱里的“扳手”则是用 CreateFileA() 和 WriteFile() 实现的。

这种设计带来了巨大的好处：可移植性。当需要将 LevelDB 移植到一个新的操作系统（比如 Fuchsia）时，开发者几乎不需要修改任何核心逻辑代码。他们只需要为新平台实现一个新的 Env 子类——也就是打造一个新的、符合标准的工具箱——然后整个 LevelDB 就可以在这个新平台上运行了。

graph BT

    subgraph "具体的平台实现"

        C["PosixEnv (Linux, macOS)"]

        D["WindowsEnv (Windows)"]

        E["MemEnv (用于测试)"]

    end

    

    subgraph "LevelDB 核心逻辑"

        A["DBImpl, Compaction, SSTable, 等..."]

    end



    subgraph "Env 抽象接口 (标准工具箱)"

        B(Env)

        B -- "提供 NewWritableFile()" --> A

        B -- "提供 StartThread()" --> A

    end

    





    A -- "调用" --> B

    C -- "实现" --> B

    D -- "实现" --o B

    E -- "实现" --o B

    

    style A fill:#cde

    style B fill:#f9f

我们如何使用 Env？

对于绝大多数用户来说，你几乎不需要直接与 Env 交互。LevelDB 会在后台为你处理好一切。

当你打开一个数据库时，选项 (Options) 对象里有一个 env 成员。如果你不设置它，它的默认值就是 Env::Default()。

Env::Default() 是一个静态方法，它会根据编译时确定的操作系统，返回一个对应平台的 Env 单例对象。在 Linux 上，它返回 PosixEnv 的实例；在 Windows 上，它返回 WindowsEnv 的实例。

#include "leveldb/db.h"

#include "leveldb/env.h"



int main() {

  leveldb::Options options;

  

  // 我们没有设置 options.env，

  // 所以 LevelDB 会自动使用 Env::Default()

  // 在 Linux 上就是 PosixEnv，在 Windows 上就是 WindowsEnv

  

  leveldb::DB* db;

  // DB::Open 内部会从 options.env 获取环境对象，

  // 并在需要时用它来操作文件、启动线程等。

  leveldb::Status status = leveldb::DB::Open(options, "/tmp/testdb", &db);

  

  // ...

  

  delete db;

  return 0;

}

所以，Env 虽然至关重要，但它就像空气一样，默默地支撑着一切，而我们通常感觉不到它的存在。

Env 内部是如何工作的？

Env 的强大之处在于它的多态设计。Env 本身是一个抽象基类，定义了所有平台都需要提供的功能接口。

1. Env 的接口定义 (include/leveldb/env.h)

Env 类定义了许多纯虚函数（以 = 0 结尾），这意味着任何想要成为一个“合格” Env 的子类都必须实现这些函数。

// 来自 include/leveldb/env.h (简化后)

class LEVELDB_EXPORT Env {

 public:

  virtual ~Env();



  // 返回一个适合当前操作系统的默认 Env

  static Env* Default();



  // 创建一个用于顺序读取的文件对象

  virtual Status NewSequentialFile(const std::string& fname,

                                   SequentialFile** result) = 0;



  // 创建一个用于随机读取的文件对象

  virtual Status NewRandomAccessFile(const std::string& fname,

                                     RandomAccessFile** result) = 0;



  // 创建一个用于写操作的文件对象

  virtual Status NewWritableFile(const std::string& fname,

                                 WritableFile** result) = 0;

  

  // 启动一个新线程

  virtual void StartThread(void (*function)(void* arg), void* arg) = 0;



  // 返回当前的微秒时间戳

  virtual uint64_t NowMicros() = 0;

  // ... 还有很多其他接口, 如文件删除、目录创建等 ...

};

这个接口就是 LevelDB 核心逻辑所依赖的“标准工具箱”的蓝图。

2. POSIX 平台的实现 (util/env_posix.cc)

PosixEnv 类继承自 Env，并使用 POSIX 标准的系统调用来实现这些接口。

让我们看看 NewWritableFile 的实现：

// 来自 util/env_posix.cc (简化后)

Status PosixEnv::NewWritableFile(const std::string& filename,

                                 WritableFile** result) {

  // 使用 POSIX 的 open() 系统调用来创建文件

  int fd = ::open(filename.c_str(),

                  O_TRUNC | O_WRONLY | O_CREAT, 0644);

  if (fd < 0) {

    *result = nullptr;

    return PosixError(filename, errno); // 返回错误状态

  }



  // 创建一个 PosixWritableFile 对象来包装文件描述符

  *result = new PosixWritableFile(filename, fd);

  return Status::OK();

}

这里，PosixEnv 将对“写文件”这个抽象请求，转换成了对 ::open() 这个具体的 POSIX 系统调用。

3. Windows 平台的实现 (util/env_windows.cc)

与之对应，WindowsEnv 则使用 Windows API 来实现同样的功能。

// 来自 util/env_windows.cc (简化后)

Status WindowsEnv::NewWritableFile(const std::string& filename,

                                   WritableFile** result) {

  // 使用 Windows API 的 CreateFileA() 来创建文件

  ScopedHandle handle = ::CreateFileA(

      filename.c_str(), GENERIC_WRITE, /*share_mode=*/0,

      /*security=*/nullptr, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL,

      /*template=*/nullptr);

  if (!handle.is_valid()) {

    *result = nullptr;

    return WindowsError(filename, ::GetLastError());

  }



  // 创建一个 WindowsWritableFile 对象来包装文件句柄

  *result = new WindowsWritableFile(filename, std::move(handle));

  return Status::OK();

}

WindowsEnv 将同样的抽象请求，转换成了对 ::CreateFileA() 这个具体的 Windows API 调用。LevelDB 的上层代码完全不知道也不关心这些差异。

Env::Default() 的魔法

Env::Default() 是如何知道该返回哪个实现的呢？这通常是通过编译时的预处理宏来完成的。

// 位于 env.cc 或平台相关的 env_*.cc 文件中 (概念简化)

#include "leveldb/env.h"



#if defined(LEVELDB_PLATFORM_POSIX)

#include "util/env_posix.h"

#elif defined(LEVELDB_PLATFORM_WINDOWS)

#include "util/env_windows.h"

#endif



namespace leveldb {

Env* Env::Default() {

  // 静态变量保证了全局只有一个实例

  static SingletonEnv<

#if defined(LEVELDB_PLATFORM_POSIX)

    PosixEnv

#elif defined(LEVELDB_PLATFORM_WINDOWS)

    WindowsEnv

#else

    // Fallback or error for unsupported platforms

#endif

  > env_container;

  return env_container.env();

}

} // namespace leveldb

在编译时，构建系统会根据目标平台定义 LEVELDB_PLATFORM_POSIX 或 LEVELDB_PLATFORM_WINDOWS，从而使得 Env::Default() 的代码在编译后，就“硬编码”为返回正确的平台特定 Env 实例。

用于测试的 MemEnv

Env 抽象层的另一个巨大好处是可测试性。LevelDB 提供了一个完全在内存中模拟文件系统的 MemEnv（位于 helpers/memenv/memenv.h）。在进行单元测试时，可以使用 MemEnv 来代替真实的 PosixEnv 或 WindowsEnv。这使得测试可以：

• 非常快：因为没有实际的磁盘 I/O。


• 完全隔离：不会在文件系统上留下任何垃圾文件。


• 可控：可以方便地模拟文件读写错误等异常情况。

总结与回顾

在本章中，我们探索了 LevelDB 的根基——Env 环境抽象层。

• Env 是一个对操作系统功能的抽象接口，它将 LevelDB 的核心逻辑与具体的平台实现解耦。


• 这个“万能工具箱”的设计使得 LevelDB 具有极高的可移植性。


• 我们通常通过 Env::Default() 间接使用它，它会自动返回适合当前操作系统的 Env 实现（如 PosixEnv 或 WindowsEnv）。


• Env 的抽象也使得编写快速、隔离的单元测试成为可能，例如使用内存文件系统 MemEnv。

至此，我们已经完成了 LevelDB 核心概念的探索之旅！让我们一起回顾一下走过的路：

我们从最基础的数据表示 数据切片 (Slice) 开始，学习了如何通过 选项 (Options)] 配置我们的 数据库实例 (DB)。我们掌握了如何使用 批量写 (WriteBatch) 和 迭代器 (Iterator) 与数据库高效交互。

然后，我们深入内部，揭开了数据持久化的第一道防线 预写日志 (Log / WAL)，看到了数据在内存中的临时住所 内存表 (MemTable)，并最终见证了它们在磁盘上的永久归宿 排序字符串表 (SSTable)。我们理解了 LevelDB 是如何通过后台的 合并 (Compaction) 任务来保持整洁，以及如何通过 版本集 (VersionSet / Version) 来管理数据快照。

我们还深入到了 SSTable 的微观世界，探索了 数据块 (Block) 的紧凑结构，并了解了 缓存 (Cache) 如何为读取加速。我们学会了用 比较器 (Comparator) 定义秩序，用 过滤器策略 (FilterPolicy) 避免无效查询。最后，我们认识了支撑这一切的平台基石 环境 (Env)。

希望这个系列能帮助你建立起对 LevelDB 内部工作原理的清晰理解。现在，你不仅知道如何使用 LevelDB，更重要的是，你明白了它为何能如此高效、稳定地工作。恭喜你完成了这段旅程！

Spec-Kit WBS：技术团队的项目管理新方式

📋 WBS基本概念

什么是WBS？

WBS (Work Breakdown Structure) = 工作分解结构

• 定义: 将项目可交付成果和项目工作分解成较小的、更易于管理的组件的过程


• 目标: 确保项目范围完整，工作不遗漏，便于估算、计划、执行和控制


• 本质: 把复杂项目像搭积木一样，一层一层地分解成可管理的小任务

WBS的核心价值

🔄 WBS与PDCA的关系

PDCA循环在项目管理中的应用

Plan (计划)

├── 项目范围定义

├── WBS创建 ← 关键工具

├── 时间估算

├── 资源分配

└── 风险管理



Do (执行)

├── 按WBS执行任务

├── 团队协作

├── 质量保证

└── 进度跟踪



Check (检查)

├── 里程碑检查

├── 质量审查

├── 进度评估

└── 偏差分析



Act (行动)

├── 纠正措施

├── 预防措施

├── 经验总结

└── 流程改进

WBS与PDCA的协同效应

关键理解: WBS是PDCA循环中Plan阶段的核心工具，它将抽象的项目目标转化为具体的、可执行的任务，确保项目管理的系统性和完整性。

🏗️ WBS实际示例：开发一个电商网站

1. 项目概述

项目名称: 开发一个在线购物网站

项目目标: 让用户可以浏览商品、下单购买、管理账户

2. WBS分解过程

第一层：主要阶段

电商网站项目

├── 1. 需求分析阶段

├── 2. 设计阶段  

├── 3. 开发阶段

├── 4. 测试阶段

└── 5. 部署上线阶段

第二层：每个阶段的工作包

电商网站项目

├── 1. 需求分析阶段

│   ├── 1.1 用户需求调研

│   ├── 1.2 功能需求分析

│   └── 1.3 技术需求分析

├── 2. 设计阶段

│   ├── 2.1 界面设计

│   ├── 2.2 数据库设计

│   └── 2.3 系统架构设计

├── 3. 开发阶段

│   ├── 3.1 前端开发

│   ├── 3.2 后端开发

│   └── 3.3 数据库开发

├── 4. 测试阶段

│   ├── 4.1 功能测试

│   ├── 4.2 性能测试

│   └── 4.3 安全测试

└── 5. 部署上线阶段

    ├── 5.1 服务器配置

    ├── 5.2 数据迁移

    └── 5.3 上线发布

第三层：具体活动（最详细的任务）

电商网站项目

├── 1. 需求分析阶段

│   ├── 1.1 用户需求调研

│   │   ├── 1.1.1 设计用户问卷

│   │   ├── 1.1.2 进行用户访谈

│   │   └── 1.1.3 分析用户反馈

│   ├── 1.2 功能需求分析

│   │   ├── 1.2.1 列出所有功能点

│   │   ├── 1.2.2 确定功能优先级

│   │   └── 1.2.3 编写需求文档

│   └── 1.3 技术需求分析

│       ├── 1.3.1 确定技术栈

│       ├── 1.3.2 评估性能要求

│       └── 1.3.3 制定技术方案

├── 2. 设计阶段

│   ├── 2.1 界面设计

│   │   ├── 2.1.1 设计首页布局

│   │   ├── 2.1.2 设计商品列表页

│   │   ├── 2.1.3 设计购物车页面

│   │   └── 2.1.4 设计用户中心

│   ├── 2.2 数据库设计

│   │   ├── 2.2.1 设计用户表

│   │   ├── 2.2.2 设计商品表

│   │   ├── 2.2.3 设计订单表

│   │   └── 2.2.4 设计购物车表

│   └── 2.3 系统架构设计

│       ├── 2.3.1 设计整体架构

│       ├── 2.3.2 设计API接口

│       └── 2.3.3 设计安全方案

├── 3. 开发阶段

│   ├── 3.1 前端开发

│   │   ├── 3.1.1 搭建前端框架

│   │   ├── 3.1.2 开发首页组件

│   │   ├── 3.1.3 开发商品展示组件

│   │   ├── 3.1.4 开发购物车组件

│   │   └── 3.1.5 开发用户中心组件

│   ├── 3.2 后端开发

│   │   ├── 3.2.1 搭建后端框架

│   │   ├── 3.2.2 开发用户管理API

│   │   ├── 3.2.3 开发商品管理API

│   │   ├── 3.2.4 开发订单管理API

│   │   └── 3.2.5 开发支付接口

│   └── 3.3 数据库开发

│       ├── 3.3.1 创建数据库

│       ├── 3.3.2 创建数据表

│       ├── 3.3.3 插入测试数据

│       └── 3.3.4 优化数据库性能

├── 4. 测试阶段

│   ├── 4.1 功能测试

│   │   ├── 4.1.1 测试用户注册登录

│   │   ├── 4.1.2 测试商品浏览功能

│   │   ├── 4.1.3 测试购物车功能

│   │   └── 4.1.4 测试下单支付功能

│   ├── 4.2 性能测试

│   │   ├── 4.2.1 测试页面加载速度

│   │   ├── 4.2.2 测试并发用户处理

│   │   └── 4.2.3 测试数据库查询性能

│   └── 4.3 安全测试

│       ├── 4.3.1 测试SQL注入防护

│       ├── 4.3.2 测试XSS攻击防护

│       └── 4.3.3 测试用户数据安全

└── 5. 部署上线阶段

    ├── 5.1 服务器配置

    │   ├── 5.1.1 购买云服务器

    │   ├── 5.1.2 配置服务器环境

    │   └── 5.1.3 安装必要软件

    ├── 5.2 数据迁移

    │   ├── 5.2.1 备份开发数据

    │   ├── 5.2.2 迁移到生产环境

    │   └── 5.2.3 验证数据完整性

    └── 5.3 上线发布

        ├── 5.3.1 部署代码到服务器

        ├── 5.3.2 配置域名和SSL

        └── 5.3.3 监控系统运行状态

3. WBS编号规则

1. 第一层：1, 2, 3, 4, 5 (主要阶段)

2. 第二层：1.1, 1.2, 1.3 (工作包)

3. 第三层：1.1.1, 1.1.2, 1.1.3 (具体活动)

4. WBS与PDCA的结合

Plan阶段 (创建WBS)

✅ 1.1.1 设计用户问卷

✅ 1.1.2 进行用户访谈  

✅ 1.1.3 分析用户反馈

Do阶段 (执行WBS)

🔄 2.1.1 设计首页布局

🔄 2.1.2 设计商品列表页

⏳ 2.1.3 设计购物车页面

Check阶段 (检查WBS)

✅ 4.1.1 测试用户注册登录 - 通过

✅ 4.1.2 测试商品浏览功能 - 通过

❌ 4.1.3 测试购物车功能 - 发现bug

Act阶段 (改进WBS)

🔧 修复购物车bug

📝 更新测试用例

🔄 重新测试购物车功能

5. 实际项目管理中的应用

任务分配表

进度跟踪

项目进度: 15%

├── 需求分析阶段: 60% (3/5个任务完成)

├── 设计阶段: 0% (0/8个任务开始)

├── 开发阶段: 0% (0/12个任务开始)

├── 测试阶段: 0% (0/9个任务开始)

└── 部署阶段: 0% (0/8个任务开始)

🎯 WBS的优势体现

A. 完整性

• ✅ 确保所有工作都被识别


• ✅ 不会遗漏重要任务


• ✅ 项目范围清晰

B. 可管理性

• ✅ 每个任务都有明确的交付物


• ✅ 任务大小适中，便于管理


• ✅ 可以分配给不同的人员

C. 可跟踪性

• ✅ 可以跟踪每个任务的进度


• ✅ 识别瓶颈和风险点


• ✅ 及时调整计划

D. 可估算性

• ✅ 每个任务可以估算时间和成本


• ✅ 便于制定项目预算


• ✅ 便于资源分配

E. 责任分配

• ✅ 每个任务可以分配给特定的人员


• ✅ 明确的责任分工


• ✅ 便于团队协作

🔧 WBS在Spec-Kit中的应用

传统WBS vs Spec-Kit WBS

核心区别对比

分解思路

• 传统WBS：按项目阶段分解（需求→设计→开发→测试→部署）


• Spec-Kit WBS：按技术实现分解（环境→测试→实现→集成→完善）

测试策略

• 传统WBS：测试放在最后，问题发现太晚


• Spec-Kit WBS：测试先行(TDD)，质量更有保障

任务标识

• 传统WBS：无特殊标识，按顺序执行


• Spec-Kit WBS：[P]标识并行任务，提高开发效率

适用场景

• 传统WBS：通用项目管理（建筑、市场、产品发布）


• Spec-Kit WBS：软件开发项目（API开发、系统集成、技术重构）

文件管理

• 传统WBS：通用描述，适合各种项目


• Spec-Kit WBS：具体文件路径，便于开发执行

传统WBS

电商网站项目

├── 1. 需求分析 (5个任务)

├── 2. 设计 (8个任务)

├── 3. 开发 (12个任务)

├── 4. 测试 (9个任务)

└── 5. 部署 (8个任务)

Spec-Kit的WBS

联调12个接口

├── 阶段 3.1: 环境设置 (3个任务)

├── 阶段 3.2: 测试先行 (13个任务) [P]

├── 阶段 3.3: 核心实现 (14个任务)

├── 阶段 3.4: 集成 (4个任务)

└── 阶段 3.5: 完善 (4个任务)

Spec-Kit WBS的特点

Spec-Kit WBS示例

联调12个接口

├── 阶段 3.1: 环境与项目设置

│   ├── T001: 创建目录结构

│   ├── T002: 初始化项目

│   └── T003 [P]: 配置工具

├── 阶段 3.2: 测试先行 (TDD)

│   ├── T004-T015: 12个接口的合约测试 [P]

│   └── T016: 集成测试

├── 阶段 3.3: 核心实现

│   ├── T017-T018: 数据模型和服务层

│   └── T019-T030: 12个接口实现

├── 阶段 3.4: 集成

│   ├── T031-T033: 服务连接和配置

│   └── T034: 集成测试

└── 阶段 3.5: 完善

    ├── T035-T037: 测试和文档

    └── T038: 最终验证

📝 总结

WBS是项目管理的核心工具，它将复杂的项目分解为可管理的小任务。与PDCA循环结合使用，可以确保项目的系统性、完整性和可跟踪性。

关键要点:

• WBS是PDCA循环中Plan阶段的核心工具


• 通过层次化分解确保项目完整性


• 每个任务都有明确的交付物和责任人


• 支持进度跟踪和风险管理


• 在Spec-Kit中与规范驱动开发完美结合

实际应用建议:

Changelog

V1.0 (2025-09-29)

• [新增] 初稿完成 - 文档基础框架建立


• [新增] 初稿完成 - 基础版本


• [新增] 添加WBS基本概念和实际应用示例


• [新增] 新增传统WBS vs Spec-Kit WBS对比分析


• [新增] 完善文档结构和可读性 - 用户体验

写在前面的话

  想直接看代码的朋友可以省略下面的历程直接翻到最底下，我把完整示例代码放在最下面

引子

  笔者最近在做项目中遇到了一件事，某个迭代我们需要对项目进行UI改造，特别是把当前正在使用的一个可编辑表格换一下UI。说是换UI，其实是换表格，因为当前在用的表格组件是项目组花钱买的，但老板应该是对这个组件的UI有别的想法（其实就是觉得丑），然后经过老大的决定，我们需要换成Element-UI的组件（Element打钱~~ ）。
  虽说组件要换，但是我们要尽可能的保留原先的功能，原来的组件，在使用上面非常贴近于Excel表格。然后，笔者开始库库干了。。。

初步实现

  为了快速实现功能，我们首先选择的是把这个可编辑表格的所有编辑项全部展示出来，这样用户就可以直接进行表格的编辑，就像这样：

  但很快，我们就发现了第一个问题。
  我们的表格中，有两列下拉框使用了远端搜索功能，同时使用了一个封装的下拉选择组件。这就使得当下拉框有值的时候，它会尝试用value在下拉选项中去匹配对应的label，而下拉选项需要通过远端搜索即调接口获取。这两列调的是同一个接口，哪怕这里做了分页并且默认一页10条，仍然默认会调同一个接口20次，这是一个很影响性能的问题，如果切换成一页20条、30条、50条的话，后果不堪设想。。。
  考虑到这种情况，我们首先采取的方法是只调一次接口，把选项数据全部拉回来本地，然后让使用这些选项的下拉框直接引用。但在这里，我们又发现，这些下拉框是这样的：

  是的，label和value同时展示出来，而且在远程搜索中，可以搜索label或value来找对应项。
  那这里我们就得使用filter-method自定义搜索方法咯，但这里有个问题，那就是搜索结果得要是独立的才行，即：第一次搜索的选项结果，不能出现在第二次的搜索选项里，意思就是每次搜索完，需要把选项还原到默认状态。这好办，visible-change事件可以实现。
  当我们把实现的功能交付出去后，产品给我们带来了一个噩耗：用户非得要跟Excel一样的，也就是说为了满足用户的使用习惯，我们需要尽可能还原出原来的表格组件来

解决之道

第一步

  事已至此，先吃饭吧，啊，不是，先百度吧
  在某次冲浪中，我发现了一篇文章，里面提到使用el-table组件的cell-dblclick事件来实现双击进入编辑状态的做法，也就是下面这样：
  通过列的prop和行的id一起来定位到双击选中的单元格的位置，然后通过v-if使得输入框渲染出来

<template>

  <el-table

    :data="tableData"

    style="width: 100%"

    @cell-dblclick="cellDblclick"

  >

    <el-table-column prop="name" label="姓名" width="180">

      <template slot-scope="scope">

        <el-input v-if="formViewMethod(scope)" v-model="scope.row.name"></el-input>

        <span v-else>{{ scope.row.name }}</span>

      </template>

    </el-table-column>

  </el-table>

</template>

<script>

export default {

  data() {

    return {

      editColumnProp: null,

      editRowId: null

    }

  },

  methods: {

    cellDblclick(row, column, cell) {

      cell.style.background = 'pink'

      this.editColumnProp = column.property

      this.editRowId = row.id

    },

    formViewMethod(scope) {

      const { row, column } = scope

      return (

        row.id === this.editRowId &&

        this.editColumnProp === column.property

      )

    }

  }

}

</script>

  这方法确实可行！在默认是text的情况下，也就不会去调接口，这样，哪怕是用回远端搜索功能，也能保证对性能没有那种压力。
  第一步走出了，另一个问题就摆在眼前了：当我点击编辑框以外的地方，该怎么让它恢复默认那种文本状态呢？文章的作者并没有给出答案，那就得自己去寻找了

新的曙光

  最近在冲浪中，我了解到有一个名为ClickOutside的指令，这是一个vue3中的自定义指令，顾名思义，就是点击外面的意思。这下子灵感就来了：在cell-dblclick事件中，我们可以获取到当前单元格的dom，那如果我们在获取dom的时候，给它加上一个点击事件，当点击到外面的时候，就清空当前单元格的选中状态，那是不是就可以实现了呢？说干就干，上代码：

cellDblclick(row, column, cell) {

  cell.style.background = 'pink'

  cell.__clickOutside__ = (e) => {

    if (cell.contains(e.target)) {

      return console.log('点击了自己')

    }

    console.log('点击了外面')

    cell.__clickOutside__ && document.removeEventListener('click', cell.__clickOutside__)

  }

  document.addEventListener('click', cell.__clickOutside__)

  this.editColumnProp = column.property

  this.editRowId = row.id

}

在这里我们使用了dom的contains()方法，这个方法用于检测一个元素是否包含另一个元素，返回的是一个布尔值。也就是当点击的时候，判断被点击元素B是否在双击的时候绑定点击事件的元素A之内，如果返回true的话，就是点击自己了，否则就是点击外面，这样就能实现清空选中状态的方法了。就像下面这样子：

到这里，可编辑表格的功能就算实现了，谢谢大家观看，下面会贴上完整的示例代码，大伙儿可以直接复制粘贴来看看效果。

完整代码

<template>

  <div class="irregular-table-container">

    <div class="custom-table">

      <!-- 表格区域 -->

      <el-table

        :data="tableData"

        style="width: 100%"

        @cell-dblclick="cellDblclick"

      >

        <el-table-column

          prop="date"

          label="日期"

          width="180">

        </el-table-column>

        <el-table-column prop="name" label="姓名" width="180">

          <template slot-scope="scope">

            <el-input v-if="formViewMethod(scope)" v-model="scope.row.name"></el-input>

            <span v-else>{{ scope.row.name }}</span>

          </template>

        </el-table-column>

        <el-table-column

          prop="gender"

          label="性别"

          width="120"

          :formatter="formatGender"

        >

        </el-table-column>

        <el-table-column

          prop="city"

          label="城市"

          width="200"

          :formatter="formatCity"

        >

        </el-table-column>

        <el-table-column prop="address" label="地址"/>

      </el-table>

    </div>

  </div>

</template>



<script>

export default {

  name: "EditableTable",

  data() {

    return {

      tableData: [

        {

          id: 1,

          date: '2016-05-02',

          name: '王小虎',

          gender: '男',

          city: 'Beijing',

          address: '上海市普陀区金沙江路 1518 弄'

        }, {

          id: 2,

          date: '2016-05-04',

          name: '王小虎',

          gender: '男',

          city: 'Nanjing',

          address: '上海市普陀区金沙江路 1517 弄'

        }, {

          id: 3,

          date: '2016-05-01',

          name: '王小虎',

          gender: '男',

          city: 'Guangzhou',

          address: '上海市普陀区金沙江路 1519 弄'

        }, {

          id: 4,

          date: '2016-05-03',

          name: '王小虎',

          gender: '男',

          city: 'Shanghai',

          address: '上海市普陀区金沙江路 1516 弄'

        }

      ],

      options: [

        { label: '男', value: 1 },

        { label: '女', value: 0 }

      ],

      cities: [

        {

          value: 'Beijing',

          label: '北京'

        }, {

          value: 'Shanghai',

          label: '上海'

        }, {

          value: 'Nanjing',

          label: '南京'

        }, {

          value: 'Chengdu',

          label: '成都'

        }, {

          value: 'Shenzhen',

          label: '深圳'

        }, {

          value: 'Guangzhou',

          label: '广州'

        }

      ],

      editColumnProp: null,

      editRowId: null

    }

  },

  computed: {},

  created() {},

  methods: {

    formatName(row) {

      const input = (

        <el-input v-model={row.name} clearable />

      )

      return input

    },

    formatGender(row) {

      const select = (

        <el-select v-model={row.gender}>

          {this.options.map(item => {

            return (

              <el-option

                key={item.value}

                label={item.label}

                value={item.value}

              />

            )

          })}

        </el-select>

      )

      return select

    },

    formatCity(row) {

      const select = (

        <el-select v-model={row.city}>

          {this.cities.map(item => {

            return (

              <el-option

                key={item.value}

                label={item.label}

                value={item.value}

              >

              <span style="float: left">{ item.label }</span>

              <span style="float: right; color: #8492a6; font-size: 13px">{ item.value }</span>

              </el-option>

            )

          })}

        </el-select>

      )

      return select

    },

    cellDblclick(row, column, cell) {

      cell.style.background = 'pink'

      cell.__clickOutside__ = (e) => {

        if (cell.contains(e.target)) {

          return console.log('点击了自己')

        }

        // console.log('点击了外面')

        this.editColumnProp = null

        this.editRowId = null

        cell.__clickOutside__ && document.removeEventListener('click', cell.__clickOutside__)

      }

      document.addEventListener('click', cell.__clickOutside__)

      this.editColumnProp = column.property

      this.editRowId = row.id

    },

    formViewMethod(scope) {

      const { row, column } = scope

      return (

        row.id === this.editRowId &&

        this.editColumnProp === column.property

      )

    }

  }

}

</script>

感谢名单

  写完一看时间，嚯，好家伙，凌晨4点了，赶紧碎觉，狗命要紧~~
  最后的最后，这里要感谢两位给我提供灵感和思路的大大，我把他们的文章链接放到下面了，感兴趣的小伙伴可以过去学习下。
vue对el-table的二次封装，双击单元格编辑，避免表格输入框过多卡顿
vue自定义指令（v-clickoutside）-点击当前区域之外的位置

在前端开发中，事件处理是交互逻辑的核心。但你是否会遇到这样的困惑：绑定事件时明明用的是父元素，触发时却总获取到子元素的信息？或是想优化大量子元素的事件绑定，却不知从何下手？

这一切的答案，都藏在 event.currentTarget和 event.target这对“双胞胎”属性里。

一、核心概念：谁在触发？谁在处理？

要理解这两个属性，首先需要明确事件流的基本概念。当用户与页面交互（如点击）时，事件会经历 ​捕获阶段 → 目标阶段 → 冒泡阶段​ 传播。而 event.currentTarget和 event.target的差异，正源于它们在这场“事件旅行”中的不同角色。

1. event.target：事件的“起点”

​定义​：触发事件的最深层元素，即用户实际交互的对象。

​特点​：

• 从事件触发到结束，始终指向最初的“罪魁祸首”（即使事件冒泡到父元素，它也不会变）。


• 可能是按钮、文本节点，甚至是动态生成的元素。

​示例​：点击一个嵌套的 <div>内部的 <span>，event.target始终是 <span>。

2. event.currentTarget：事件的“处理者”

​定义​：当前正在执行事件处理程序的元素，即绑定事件监听器的那个元素。

​特点​：

• 随着事件在捕获/冒泡阶段流动，它的值会动态变化（从外层元素逐渐向内，或从内层向外）。


• 在非箭头函数的回调中，this等价于 event.currentTarget。

​示例​：父元素绑定点击事件，子元素被点击时，父元素的回调函数中 event.currentTarget是父元素，而 event.target是子元素。

二、一张图看懂：事件流中的身份切换

为了更直观理解二者的差异，我们通过一个三层嵌套结构的交互演示：

<div id="outer" class="box">外层（绑定事件）

  <div id="middle" class="box">中层

    <div id="inner" class="box">内层（点击我）</div>

  </div>

</div>

当点击最内层的 inner元素时，事件流的三个阶段中，currentTarget和 target的变化如下：

​关键结论​：

• target是“事件的源头”，永远指向用户点击的那个元素。


• currentTarget是“事件的搬运工”，随事件传播阶段变化，指向当前处理事件的元素。

三、为什么需要事件委托？用差异解决实际问题

传统事件绑定方式为每个子元素单独添加监听器，但在动态列表、表格等场景下，这会导致 ​内存浪费、动态元素难维护、代码冗余​ 三大痛点。而事件委托的出现，正是利用 currentTarget和 target的差异，提供了一种“集中管理、按需处理”的优化方案。

事件委托的核心逻辑

​原理​：将子元素的事件监听绑定在父元素上，利用事件冒泡机制，由父元素统一处理子元素的事件。

​关键依赖​：

• 父元素（currentTarget）负责接收事件。


• 通过 event.target识别实际触发的子元素，执行针对性逻辑。

经典场景实战

场景 1：动态待办列表的点击交互

需求：点击待办项标记完成，支持动态添加新任务。

​传统方式的问题​：每次新增任务都要重新绑定事件，代码冗余且易出错。

​事件委托方案​：

<ul id="todoList">

  <li class="todo-item">任务 1（点击标记完成）</li>

  <li class="todo-item">任务 2（点击标记完成）</li>

</ul>

<button id="addTodo">添加新任务</button>

const todoList = document.getElementById('todoList');

const addTodoBtn = document.getElementById('addTodo');



// 父元素 todoList 绑定唯一点击事件（冒泡阶段）

todoList.addEventListener('click', function(event) {

  // event.target 是实际点击的元素（可能是 li 或其子元素）

  const target = event.target.closest('.todo-item'); // 向上查找最近的 li

  

  if (!target) return; // 非目标元素，跳过

  

  // 标记完成（切换类名）

  target.classList.toggle('completed');

  

  // 若点击删除按钮（假设子元素有 .delete-btn）

  if (target.querySelector('.delete-btn')) {

    target.remove(); // 直接删除父元素 li

  }

});



// 动态添加新任务（无需重新绑定事件）

addTodoBtn.addEventListener('click', () => {

  const newTodo = document.createElement('li');

  newTodo.className = 'todo-item';

  newTodo.innerHTML = `新任务 ${Date.now()} <button class="delete-btn">删除</button>`;

  todoList.appendChild(newTodo);

});

​优势​：

• 仅需绑定一次父元素事件，内存占用极低。


• 新增任务自动继承事件处理能力，无需额外代码。

场景 2：表格单元格的双击编辑

需求：双击表格单元格（td）转换为输入框编辑。

​事件委托方案​：

<table id="dataTable">

  <thead><tr><th>ID</th><th>名称</th></tr></thead>

  <tbody>

    <tr><td>1</td><td>苹果</td></tr>

    <tr><td>2</td><td>香蕉</td></tr>

  </tbody>

</table>

const dataTable = document.getElementById('dataTable');



// 父元素 tbody 监听双击事件（冒泡到 tbody）

dataTable.addEventListener('dblclick', function(event) {

  // event.target 是实际双击的元素（可能是文本或 td）

  const td = event.target.closest('td');

  if (!td) return;

  

  // 转换为输入框编辑

  const originalText = td.textContent;

  td.innerHTML = `<input type="text" value="${originalText}" class="edit-input">`;

  

  const input = td.querySelector('.edit-input');

  input.focus();

  

  // 输入完成后保存（监听输入框失焦）

  input.addEventListener('blur', () => {

    td.textContent = input.value;

  });

});

​优势​：

• 无论表格有多少行，只需绑定一次 tbody事件。


• 新增行（如 AJAX 加载数据后插入）自动支持编辑功能。

四、避坑指南：事件委托的注意事项

五、总结：从“混淆”到“精通”的关键

event.currentTarget和 event.target的核心差异，本质是 ​​“处理者”与“触发者”​​ 的分工：

• target是用户交互的起点，始终指向实际触发的元素。


• currentTarget是事件处理程序的载体，随事件传播阶段变化。

而事件委托，正是利用这一差异，通过父元素（currentTarget）集中处理子元素事件，解决了动态内容、批量操作的维护难题。

掌握这对属性和事件委托模式，不仅能写出更高效的代码，更能让你在前端交互设计中游刃有余。下次遇到大量子元素的事件绑定需求时，不妨试试事件委托——它会是你最可靠的“效率工具”。

关注我的公众号：【编程朝花夕拾】，可获取首发内容。

01 引言

在现代Web应用开发中，模板引擎是实现前后端分离和视图渲染的重要工具。SpringBoot作为流行的Java开发框架，天然支持多种模板引擎。

每一个项目使用单一的模板引擎是标准输出。但是，总有一些老项目经历多轮迭代，人员更替，不同的开发都只是用自己熟悉的模版引擎，导致一个项目中包含了多种模板引擎。从而相互影响，甚至出现异常。这也是小编正在经历的痛苦。

本文将详细介绍如何在SpringBoot项目中同时集成JSP、Freemarker和Thymeleaf三种模板引擎，包括配置方法、使用场景、常见问题及解决方案。

02 项目搭建

本文基于Springboot 3.0.13，因为不同版本（2.x）对于部分包的做了更改。由于JSP的配置会影响其他的模板引擎，所以JSP的配置，放到最后说明。

2.1 Maven依赖

<!-- freemarker 模版引擎 -->

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-freemarker</artifactId>

</dependency>

<!-- thymeleaf 模版引擎 -->

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-thymeleaf</artifactId>

</dependency>

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-web</artifactId>

</dependency>

2.3 配置

#配置freemarker

spring.freemarker.template-loader-path=classpath:/templates/ftl/

spring.freemarker.suffix=.ftl

spring.freemarker.cache=false



# 配置thymeleaf

spring.thymeleaf.prefix=classpath:/templates/html/

spring.thymeleaf.suffix=.html

spring.thymeleaf.cache=false

2.4 最佳实践

页面

控制层

@Controller

@RequestMapping("/page")

public class PageController {

    

    @RequestMapping("{engine}")

    public String toPage(@PathVariable("engine") String engine, Model model) {

        model.addAttribute("date", new Date());

        return engine + "_index";

    }

}

2.5 测试

到这里，会发现一切顺利。Thymeleaf和Freemarker都可以顺利解析。但是，引入JSP之后，发现不能生效。

03 SpringBoot继续集成JSP

3.1 Maven依赖

<!-- JSP支持 -->

<dependency>

    <groupId>org.apache.tomcat.embed</groupId>

    <artifactId>tomcat-embed-jasper</artifactId>

</dependency>

<!-- jstl 工具 -->

<dependency>

    <groupId>jakarta.servlet.jsp.jstl</groupId>

    <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>

</dependency>

<dependency>

    <groupId>org.glassfish.web</groupId>

    <artifactId>jakarta.servlet.jsp.jstl</artifactId>

</dependency>

这里要说明的jstl，低版本（3.x一下）的需要引入:

<dependency>

    <groupId>javax.servlet</groupId>

    <artifactId>jstl</artifactId>

    <version>1.2</version>

</dependency>

具体的依赖可以在Springboot官方文档中查看。

3.2 配置

spring.mvc.view.prefix=/WEB-INF/jsp/

spring.mvc.view.suffix=.jsp

3.3 创建包结构

因为SpringBoot默认不支持JSP，所以需要我们自己配置支持JSP。

包的路径地址：\src\main\webapp\WEB-INF

3.4 修改pom打包

在build下增加resource

<resources>

    <!-- 打包时将jsp文件拷贝到META-INF目录下-->

    <resource>

        <!-- 指定处理哪个目录下的资源文件 -->

        <directory>src/main/webapp</directory>

        <!--注意此次必须要放在此目录下才能被访问到-->

        <targetPath>META-INF/resources</targetPath>

        <includes>

            <include>**/**</include>

        </includes>

    </resource>

</resources>

3.5 测试

其他两个不受影响，但是发现配置的JSP并不生效，根据报错信息来看，默认使用了Thymeleaf解析的。

04 源码追踪

关键的类：org.springframework.web.servlet.view.ContentNegotiatingViewResolver

断点调试发现，图中①根据jsp_index视图，可以发现两个候选的View：ThymelearView和JstlView。

图中②获取最优的视图返回了ThymelearView，从而解析错误。从getBestView()源码可以看到，仅仅做了遍历操作，并没有个给句特殊的规则去取。如图：

所以影响视图解析器的就是候选视图的顺序。

我们继续看候选视图的取值：

这里仍是只是遍历，我们需要继续追溯this.viewResolvers的来源：

关键代码AnnotationAwareOrderComparator.sort(this.viewResolvers)会对所有的视图排序，所以我们只需要指定JSP的视图为第一个就可以了。

05 配置JSP视图的顺序

因为JSP的视图使用的是InternalResourceViewResolver，所以我们只需要设置其顺序即可。

@Configuration

public class BeanConfig {



    @Autowired

    InternalResourceViewResolver resolver;



    @PostConstruct

    public void init() {

        resolver.setOrder(1);

    }

由于其他的视图解析器默认是最级别，所以这里的设置只要比Integr.MAX小即可。

测试

我们发现源代码已经将JstlView变成了第一个，最优的视图自然也选择了JstlView，如图：

效果

我们发现JSP是正常显示了，但是其他两个又不好了。

真实让人头大!

06 解决JSP混合问题

6.1 解决方案

其实这里要使用一个属性可以永久的解决问题：viewName，

每一个ViewResolver都有一段关键的源码：

这里是匹配关系，可以通过配置的view-names过滤不符合条件的视图：

6.2 重新修改配置

###配置freemarker

spring.freemarker.template-loader-path=classpath:/templates/

spring.freemarker.view-names=ftl/*

spring.freemarker.suffix=.ftl

spring.freemarker.cache=false

#

### 配置thymeleaf

spring.thymeleaf.prefix=classpath:/templates/

spring.thymeleaf.view-names=html/*

spring.thymeleaf.suffix=.html

spring.thymeleaf.cache=false

##

### 配置JSP

spring.mvc.view.prefix=/WEB-INF/

spring.mvc.view.suffix=.jsp

这里的和之前不同的就是增加了spring.thymeleaf.view-names、spring.freemarker.view-names，并且classpath的路径少了一部分移动到view-names里面了。

JSP的spring.mvc.view.prefix同样少了一部分需要配置。

6.3 重新修改Java配置

@Configuration

public class BeanConfig {



    @Autowired

    InternalResourceViewResolver resolver;



    @PostConstruct

    public void init() {

        resolver.setViewNames("jsp/*");

    }

也可以使用Bean定义。使用Bean定义需要删除配置文件关于JSP的配置。

@Bean

public ViewResolver jspViewResolver() {

    InternalResourceViewResolver resolver = new InternalResourceViewResolver();

    resolver.setPrefix("/WEB-INF/");

    resolver.setSuffix(".jsp");

    resolver.setViewNames("jsp/*");

    return resolver;

}

6.4 修改控制层

@Controller

@RequestMapping("/page")

public class PageController {

 

    @RequestMapping("{engine}")

    public String toFtl(@PathVariable("engine") String engine, Model model) {

        model.addAttribute("date", new Date());

        return engine + "/" + engine + "_index";

    }

}

6.5 效果

// 基础 GET 请求

fetch('https://api.example.com/data')

  .then(response => {

    if (!response.ok) throw new Error('Network error');

    return response.json(); // 需手动解析JSON

  })

  .then(data => console.log(data))

  .catch(error => console.error('Request failed:', error));

const controller = new AbortController();

fetch(url, { signal: controller.signal });

controller.abort(); // 取消请求

// 完整特性的 POST 请求

axios.post('https://api.example.com/users', {

    name: 'John',

    age: 30

  }, {

    headers: { 'X-Custom-Header': 'value' },

    timeout: 5000

  })

  .then(response => console.log(response.data)) // 自动解析JSON

  .catch(error => {

    if (axios.isCancel(error)) {

      console.log('Request canceled');

    } else {

      console.error('Request error:', error);

    }

  });

// 身份验证拦截器

axios.interceptors.request.use(config => {

  config.headers.Authorization = `Bearer ${token}`;

  return config;

});



// 错误统一处理

axios.interceptors.response.use(

  response => response,

  error => {

    alert(`API Error: ${error.response.status}`);

    return Promise.reject(error);

  }

);

const source = axios.CancelToken.source();

axios.get(url, { cancelToken: source.token });

source.cancel('Operation canceled');

4. 客户端防御：内置 XSRF 防护
5. 进度跟踪：上传/下载进度监控
6. 多环境支持：浏览器与 Node.js 通用

关键决策因素对比

2025 年选型建议

融合解决方案

在大型项目中，可以采用混合方案：

// 封装原生fetch获得axios式体验

const http = async (url, options = {}) => {

  const controller = new AbortController();

  const config = {

    ...options,

    signal: controller.signal,

    headers: { 'Content-Type': 'application/json', ...options.headers }

  };



  const timeoutId = setTimeout(() => controller.abort(), 8000);



  try {

    const response = await fetch(url, config);

    clearTimeout(timeoutId);

    

    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    return await response.json();

  } catch (error) {

    if (error.name === 'AbortError') console.error('Request timed out');

    throw error;

  }

};

结论

在 2025 年的技术背景下，Fetch API 的原生能力得到大幅增强，对于小型项目和简单场景愈发得心应手。但对于企业级应用，Axios 仍然凭借其人性化设计和功能完备性保持不可替代的地位。建议开发者根据项目的规模、运行环境、团队习惯三大核心因素制定技术决策，必要时可进行混合封装以平衡开发效率与性能要求。

JVM内存公寓清洁指南：G1与ZGC清洁工大比拼 🧹

引言：当内存公寓遇上"清洁工天团"

当 Java 应用中的对象在"内存公寓"里肆意"开派对"后，未被引用的对象便成了散落各处的"垃圾"，此时就需要专业的"清洁团队"——垃圾回收器登场。JVM 内存区域如同"内存公寓"的不同房间，其中线程共享区的堆是最大的"活动空间"，按对象生命周期分为新生代（Eden 区占 8/10、Survivor 区各占 1/10）和老年代，如同公寓的"青年宿舍"与"长者公寓"；方法区（元空间）则类似"物业档案室"，存储类元数据等。

为什么有的"清洁工"习惯按区域分片打扫，有的却能以"闪电速度"完成全屋清洁？这就不得不提到 G1 和 ZGC 两位"王牌清洁工"——前者以"分区管理"策略著称，后者则追求"低延迟闪电清洁"，其设计目标是将应用暂停（STW）时间控制在 10ms 以内，且停顿时间不会随堆大小或活跃对象增加而延长。

核心差异预告：G1 采用分代分区管理模式，擅长平衡吞吐量与停顿；ZGC 则通过创新算法突破堆大小限制，主打"毫秒级响应"。本文将拆解两者的"清洁秘籍"（垃圾回收算法）与"工资参数"（调优参数），揭秘谁能成为"内存公寓"的最优解。

G1回收器：精打细算的"分区清洁队长"

Garbage-First (G1) 垃圾收集器作为默认低延迟收集器，其核心设计理念可类比为"内存公寓"的分区清洁管理系统。与传统收集器将堆内存划分为固定大小新生代与老年代的方式不同，G1采用"分区垃圾袋"式的Region机制，将整个堆内存划分为最多2048个独立Region，每个Region容量可在1MB至32MB之间动态调整（默认根据堆大小自动选择）。这些Region并非固定归属新生代或老年代，而是根据应用内存分配模式动态标记为Eden区、Survivor区或Old区，实现内存资源的弹性调度。这种动态分区机制使G1能够灵活应对不同类型应用的内存需求，尤其适用于堆内存4GB至32GB的常规企业应用场景。

G1的垃圾回收策略采用"混合清洁模式"（Mixed GC），其工作流程可形象比喻为"先集中清理垃圾密集的房间（新生代），再抽空打扫老房间（老年代）"。G1优先对新生代Region执行Minor GC，通过复制算法快速回收短期存活对象；当老年代Region占比达到参数-XX:InitiatingHeapOccupancyPercent（默认45%）设定的阈值时，触发Mixed GC，在新生代收集的同时，选取部分垃圾占比高的老年代Region进行回收。这种选择性回收策略使G1能够集中资源处理垃圾密集区域，从而更精准地控制停顿时间，避免传统收集器对整个老年代进行全区域扫描的高昂成本。

在实际调优中，启用G1需通过JVM参数显式配置，基础命令示例如下：java -XX:+UseG1GC -Xms4g -Xmx4g -XX:MaxGCPauseMillis=200 -jar app.jar。某电商交易系统优化案例显示，在未调优状态下GC停顿时间常达300ms，通过设置MaxGCPauseMillis=200并调整Region大小后，停顿时间稳定降至180ms，同时吞吐量保持98%以上。核心调优参数及说明如下表所示：

💡 调优技巧：设置合理的停顿目标（如200ms）是平衡延迟与吞吐量的关键。G1会根据历史回收数据动态调整Region回收数量，过度严苛的停顿目标（如50ms）会迫使收集器频繁进行小范围压缩，反而导致GC次数激增。建议通过-XX:G1HeapRegionSize参数将Region大小设置为堆内存的1/2048，确保每个Region既能容纳大对象，又避免过小Region导致的管理开销。

🚨 常见误区：不要将-Xms和-Xmx设置为不同值！动态堆扩容会导致"内存公寓"频繁调整垃圾袋大小，引发额外性能开销，就像清洁工频繁更换垃圾桶尺寸一样影响效率。

以下是G1调优前后的GC日志对比：

# 调优前（停顿300ms）

[GC pause (G1 Evacuation Pause) (young) 1024M->768M(4096M) 302.5ms]

​

# 调优后（停顿180ms）

[GC pause (G1 Evacuation Pause) (young) 1024M->768M(4096M) 178.3ms]

ZGC回收器：闪电般的"极速清洁特工"

ZGC作为JVM内存管理的"极速清洁特工"，其核心竞争力体现在毫秒级停顿与超大堆支持两大特性上。设计目标明确为停顿时间不超过10ms，且该指标不会随堆大小或活跃对象数量的增加而退化，从根本上解决了传统回收器在大堆场景下的停顿痛点。

ZGC的"闪电清洁"秘籍

ZGC实现"边打扫边让住户正常活动"的核心技术在于染色指针与内存多重映射。染色指针技术在64位指针中嵌入4位元数据，可实时存储对象的标记状态与重定位信息，相当于清洁工佩戴的"AR智能眼镜"，能在不中断住户活动的情况下完成垃圾标记。内存多重映射则通过将物理内存同时映射到Marked0、Marked1、Remapped三个虚拟视图，实现并发重定位操作，确保回收过程与应用线程几乎无干扰。实测数据显示，ZGC停顿时间平均仅1.09ms，99.9%分位值为1.66ms，远低于10ms的设计阈值。

大堆管理：从16MB到16TB的"超级公寓"

与G1固定大小的Region（最大32MB）不同，ZGC采用动态Region机制，将内存划分为小页（2MB）、中页（32MB）和大页（N×2MB，最大支持16TB），如同"能伸缩的智能垃圾袋"，可根据对象大小自动调整容量。这种设计使其支持从8MB到16TB的堆内存范围，而G1在堆大小超过64GB时易出现停顿失控[1]。动态Region不仅提升了内存利用率，还解决了大对象分配效率问题，实现"小到零食包装，大到家具"的全覆盖管理。

调优参数实战

启用与核心参数配置

启用ZGC需在JDK15+环境中使用以下命令：

java -XX:+UseZGC -Xms16g -Xmx16g -XX:ZCollectionInterval=60 -jar app.jar

该配置指定16GB堆空间（初始与最大堆相同），至少每60秒执行一次回收。以下为核心参数说明：

💡 调优黄金法则：ZGC在32GB以上大堆场景优势显著，此时其停顿稳定性远超G1；而8GB以下小堆场景建议保留G1，因ZGC的吞吐量损失（通常<15%）在小堆下性价比更低。

🚨 误区警示：ZGC在JDK15才正式发布，JDK11-14为实验性版本，存在功能限制；JDK11以下版本完全不支持，切勿尝试在低版本JDK中启用。

性能对比与GC日志示例

在64GB堆环境下，ZGC与G1的表现差异显著：

# ZGC日志（停顿8ms）

[0.875s][info][gc] GC(0) Pause Relocate Start 1.56ms

[0.877s][info][gc] GC(0) Pause Relocate End 0.89ms

​

# G1日志（停顿520ms）

[GC pause (G1 Evacuation Pause) (mixed) 5890M->4520M(65536M) 520.3ms]

某支付系统迁移案例显示，将G1替换为ZGC后，峰值GC停顿从280ms降至8ms，交易成功率提升0.5%，验证了ZGC在关键业务场景的性能优势。

G1 vs ZGC：清洁团队终极PK

衡量垃圾收集器的三项重要指标包括内存占用（Footprint）、吞吐量（Throughput）和延迟（Latency）。吞吐量和延迟通常不可兼得，关注吞吐量的收集器和关注延迟的收集器在算法选择上存在差异。以下从核心能力与场景适配两方面对比 G1 与 ZGC 的差异：

核心能力对比表

电商订单系统：用户下单高峰期需避免卡顿，ZGC 小于 10 ms 的停顿特性可保障交易流畅性。

大数据批处理：当堆大小适中（如 32 GB）且吞吐量优先时，G1 更具成本效益。

实时游戏服务：毫秒级响应要求下，ZGC 是唯一能满足低延迟需求的选择。

总结：选对清洁工，内存公寓更舒心

回到"内存公寓"的管理视角，垃圾回收器的选择本质是匹配"公寓规模"与"住户需求"的过程——正如现实中没有万能的清洁工，JVM 内存管理也不存在绝对最优解，只有最适配场景的选择。

G1 作为"精打细算的分区管理员"，擅长处理 4GB~32GB 堆内存的常规企业应用，通过区域化内存布局与增量回收机制，在延迟控制与吞吐量之间取得平衡，成为大多数标准业务场景的默认选择。其设计理念如同经验丰富的物业经理，通过精细化分区管理确保日常运营的稳定高效。

ZGC 则是"追求极致速度的闪电特工"，专为 8MB~16TB 超大堆场景打造，尤其适用于金融交易等对停顿时间（<10ms）要求严苛的低延迟应用。它突破传统回收器的性能瓶颈，如同配备尖端装备的特种清洁团队，能在不干扰住户正常活动的前提下完成超大空间的极速清理。

调优核心口诀："小堆 G1 看停顿，大堆 ZGC 保延迟，参数设置要合理，日志监控不能停"。这一实践准则强调：堆内存规模与延迟需求是选型的首要依据，而持续的参数优化与监控分析则是维持长期稳定的关键。

选择合适的垃圾回收器并合理配置参数（如元空间大小、回收阈值等），是确保"内存公寓"长期整洁（避免内存溢出、减少 GC 停顿）的核心保障。你的内存公寓需要哪种清洁工？评论区聊聊你的调优故事吧！🎉

Explain总览图 这篇文章主要看图

Explain是啥

1、Explain工具介绍

使用EXPLAIN关键字可以模拟优化器执行SQL语句，分析你的查询语句或是结构的性能瓶颈， 在 select 语句之前增加 explain 关键字，MySQL 会在查询上设置一个标记，执行查询会返回执行计划的信息，而不是执行这条SQL。

注意：如果 from 中包含子查询，仍会执行该子查询，将结果放入临时表中。

2、Explain分析示例

参考官方文档：dev.mysql.com/doc/refman/…

# 示例表：



DROP TABLE IF EXISTS `actor`;

CREATE TABLE `actor` (

`id` int(11) NOT NULL,

`name` varchar(45) DEFAULT NULL,

`update_time` datetime DEFAULT NULL,

PRIMARY KEY (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;





INSERT INTO `actor` (`id`, `name`, `update_time`) VALUES (1,'a','2017‐12‐22

15:27:18'), (2,'b','2017‐12‐22 15:27:18'), (3,'c','2017‐12‐22 15:27:18');



DROP TABLE IF EXISTS `film`;

CREATE TABLE `film` (

`id` int(11) NOT NULL AUTO_INCREMENT,

`name` varchar(10) DEFAULT NULL,

PRIMARY KEY (`id`),

KEY `idx_name` (`name`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;





INSERT INTO `film` (`id`, `name`) VALUES (3,'film0'),(1,'film1'),(2,'film2');



DROP TABLE IF EXISTS `film_actor`;

CREATE TABLE `film_actor` (

`id` int(11) NOT NULL,

`film_id` int(11) NOT NULL,

`actor_id` int(11) NOT NULL,

`remark` varchar(255) DEFAULT NULL,

PRIMARY KEY (`id`),

KEY `idx_film_actor_id` (`film_id`,`actor_id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;



INSERT INTO `film_actor` (`id`, `film_id`, `actor_id`) VALUES (1,1,1),(2,1,2),(3,2,1);





explain select * from actor;

 

# 在查询中的每个表会输出一行，如果有两个表通过 join 连接查询，那么会输出两行。

3、explain 两个变种

• 1）explain extended：

会在 explain 的基础上额外提供一些查询优化的信息。紧随其后通过 show warnings 命令可 以得到优化后的查询语句，从而看出优化器优化了什么。额外还有 filtered 列，是一个半分比的值，rows * filtered/100 可以估算出将要和 explain 中前一个表进行连接的行数（前一个表指 explain 中的id值比当前表id值小的表）

explain extended select * from film where id = 1;

show warnings;

• 2）explain partitions：

相比 explain 多了个 partitions 字段，如果查询是基于分区表的话，会显示查询将访问的分区。

4、explain中的列

4.1. id列

id列的编号是 select 的序列号，有几个 select 就有几个id，并且id的顺序是按 select 出现的顺序增长的。 id列越大执行优先级越高，id相同则从上往下执行，id为NULL最后执行。

4.2. select_type列

select_type 表示对应行是简单还是复杂的查询。

• 1）simple：简单查询。查询不包含子查询和union;


• 2）primary：复杂查询中最外层的select ;


• 3）subquery：包含在 select 中的子查询（不在 from 子句中）;


• 4）derived：包含在 from 子句中的子查询。MySQL会将结果存放在一个临时表中；


• 5）union：在 union 中的第二个和随后的 select；

explain select * from film where id = 2;

用这个例子来了解 primary、subquery 和 derived 类型：

#关闭mysql5.7新特性对衍生表的合并优化

set session optimizer_switch='derived_merge=off';



explain select (select 1 from actor where id = 1) from (select * from film where id = 1) der;

#还原默认配置

set session optimizer_switch='derived_merge=on'; 

explain select 1 union all select 1;

4.3. table列

这一列表示 explain 的一行正在访问哪个表。
当 from 子句中有子查询时，table列是格式，表示当前查询依赖 id=N 的查询，于是先执行 id=N 的查询。当有 union 时，UNION RESULT 的 table 列的值为，1和2表示参与 union 的 select 行id。

4.4. type列

这一列表示关联类型或访问类型，即MySQL决定如何查找表中的行，查找数据行记录的大概范围。 依次从最优到最差分别为：system > const > eq_ref > ref > range > index > ALL 。
一般来说，得保证查询达到range级别，最好达到ref ；

NULL：

mysql能够在优化阶段分解查询语句，在执行阶段用不着再访问表或索引。例如：在索引列中选取最小值，可 以单独查找索引来完成，不需要在执行时访问表

mysql> explain select min(id) from film;

const, system：

mysql能对查询的某部分进行优化并将其转化成一个常量（可以看show warnings 的结果）。用于 primary key 或 unique key 的所有列与常数比较时，所以表最多有一个匹配行，读取1次，速度比较快。system是 const的特例，表里只有一条元组匹配时为system；

explain extended select * from (select * from film where id = 1) tmp;

show warnings;

eq_ref：

primary key 或 unique key 索引的所有部分被连接使用 ，最多只会返回一条符合条件的记录。这可能是在 const 之外最好的联接类型了，简单的 select 查询不会出现这种 type。

explain select * from film_actor left join film on film_actor.film_id = film.id;

ref：相比 eq_ref，不使用唯一索引，而是使用普通索引或者唯一性索引的部分前缀，索引要和某个值相比较，可能会 找到多个符合条件的行。

简单 select 查询，name是普通索引（非唯一索引）

explain select * from film where name = 'film1';

关联表查询，idx_film_actor_id是film_id和actor_id的联合索引，这里使用到了film_actor的左边前缀film_id部分。

explain select film_id from film left join film_actor on film.id = film_actor.fi
lm_id;

range：

范围扫描通常出现在 in(), between ,> ,= 等操作中。使用一个索引来检索给定范围的行。

explain select * from actor where id > 1;

index：

扫描全索引就能拿到结果，一般是扫描某个二级索引，这种扫描不会从索引树根节点开始快速查找，而是直接 对二级索引的叶子节点遍历和扫描，速度还是比较慢的，这种查询一般为使用覆盖索引，二级索引一般比较小，所以这 种通常比ALL快一些。

explain select * from film;

ALL：

即全表扫描，扫描你的聚簇索引的所有叶子节点.通常情况下这需要增加索引来进行优化。

explain select * from actor;

4.5. possible_keys列

这一列显示查询可能使用哪些索引来查找 explain 时可能出现 possible_keys 有列，而 key 显示 NULL 的情况，这种情况是因为表中数据不多，mysql认为索引对此查询帮助不大，选择了全表查询。 如果该列是NULL，则没有相关的索引。在这种情况下，可以通过检查 where 子句看是否可以创造一个适当的索引来提 高查询性能，然后用 explain 查看效果。

4.6. key列

这一列显示mysql实际采用哪个索引来优化对该表的访问。 如果没有使用索引，则该列是 NULL。如果想强制mysql使用或忽视possible_keys列中的索引，在查询中使用 force index、ignore index。

4.7. key_len列

这一列显示了mysql在索引里使用的字节数，通过这个值可以算出具体使用了索引中的哪些列。 举例来说，film_actor的联合索引 idx_film_actor_id 由 film_id 和 actor_id 两个int列组成，并且每个int是4字节。通 过结果中的key_len=4可推断出查询使用了第一个列：film_id列来执行索引查找。

explain select * from film_actor where film_id = 2;

key_len计算规则如下：

     字符串：

                    char(n)：如果存汉字长度就是 3n 字节       

                    varchar(n)：如果存汉字则长度是 3n + 2 字节，加的2字节用来存储字符串长度，

                                        因为 varchar是变长字符串

char(n)和varchar(n)，5.0.3以后版本中，n均代表字符数，而不是字节数，
如果是 utf-8，一个数字 或字母占1个字节，一个汉字占3个字节 ；

    数值类型：

                    tinyint：1字节

                    smallint：2字节

                    int：4字节

                    bigint：8字节

     时间类型：

                    date：3字节

                    timestamp：4字节

                    datetime：8字节

如果字段允许为 NULL，需要1字节记录是否为 NULL ；索引最大长度是768字节，当字符串过长时，mysql会做一个类似左前缀索引的处理，将前半部分的字符提取出来做索引。

4.8. ref列

这一列显示了在key列记录的索引中，表查找值所用到的列或常量，
常见的有：const（常量），字段名（例：film.id）

4.9. rows列

这一列是mysql估计要读取并检测的行数，注意这个不是结果集里的行数。

4.10. Extra列

这一列展示的是额外信息。常见的重要值如下：

1）Using index：使用覆盖索引

覆盖索引定义：mysql执行计划explain结果里的key有使用索引，如果select后面查询的字段都可以从这个索引的树中 获取，这种情况一般可以说是用到了覆盖索引，extra里一般都有using index；覆盖索引一般针对的是辅助索引，整个 查询结果只通过辅助索引就能拿到结果，不需要通过辅助索引树找到主键，再通过主键去主键索引树里获取其它字段值。

explain select film_id from film_actor where film_id = 1;

2）Using where：

使用 where 语句来处理结果，并且查询的列未被索引覆盖

explain select * from actor where name = 'a';

3）Using index condition：

查询的列不完全被索引覆盖，where条件中是一个前导列的范围；

explain select * from film_actor where film_id > 1;

4）Using temporary：

mysql需要创建一张临时表来处理查询。出现这种情况一般是要进行优化的，首先是想到用索 引来优化。

actor.name没有索引，此时创建了张临时表来distinct

explain select distinct name from actor;

film.name建立了idx_name索引，此时查询时extra是using index,没有用临时表

explain select distinct name from film;

5）Using filesort：

将用外部排序而不是索引排序，数据较小时从内存排序，否则需要在磁盘完成排序。这种情况下一 般也是要考虑使用索引来优化的

1 mysql> explain select * from actor order by name
2. film.name建立了idx_name索引,此时查询时extra是using index

explain select * from film order by name;

6）Select tables optimized away：

使用某些聚合函数（比如 max、min来访问存在索引的某个字段是

explain select min(id) from film;

索引最佳实践

# 示例表：

CREATE TABLE `employees` (

`id` int(11) NOT NULL AUTO_INCREMENT,

`name` varchar(24) NOT NULL DEFAULT '' COMMENT '姓名',

`age` int(11) NOT NULL DEFAULT '0' COMMENT '年龄',

`position` varchar(20) NOT NULL DEFAULT '' COMMENT '职位',

`hire_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '入职时间',

PRIMARY KEY (`id`),

 KEY `idx_name_age_position` (`name`,`age`,`position`) USING BTREE

) ENGINE=InnoDB AUTO_INCREMENT=4 DEFAULT CHARSET=utf8 COMMENT='员工记录表';



INSERT INTO employees(name,age,position,hire_time) VALUES('LiLei',22,'manager',NOW());

INSERT INTO employees(name,age,position,hire_time) VALUES('HanMeimei',

23,'dev',NOW());

INSERT INTO employees(name,age,position,hire_time) VALUES('Lucy',23,'dev',NOW());

5.1.全值匹配

1 EXPLAIN SELECT * FROM employees WHERE name= 'LiLei';

1 EXPLAIN SELECT * FROM employees WHERE name= 'LiLei' AND age = 22;

EXPLAIN SELECT * FROM employees WHERE name= 'LiLei' AND age = 22 AND position ='manager';

5.2.最左前缀法则

如果索引了多列，要遵守最左前缀法。则指的是查询从索引的最左前列开始并且不跳过索引中的列。

1 EXPLAIN SELECT * FROM employees WHERE name = 'Bill' and age = 31;
2 EXPLAIN SELECT * FROM employees WHERE age = 30 AND position = 'dev';
3 EXPLAIN SELECT * FROM employees WHERE position = 'manager'

5.3.不在索引列上做任何操作（计算、函数、（自动or手动）类型转换），会导致索引失效而转向全表扫描

1 EXPLAIN SELECT * FROM employees WHERE name = 'LiLei';
2 EXPLAIN SELECT * FROM employees WHERE left(name,3) = 'LiLei';
给hire_time增加一个普通索引：

1 ALTER TABLE employees ADD INDEX idx_hire_time (hire_time) USING BTREE ;
2 EXPLAIN select * from employees where date(hire_time) ='2018‐09‐30';

转化为日期范围查询，有可能会走索引：

1 EXPLAIN select * from employees where hire_time >='2018‐09‐30 00:00:00' and hire_time <='2018‐09‐30 23:59:59';

还原最初索引状态

1 ALTER TABLE employees DROP INDEX idx_hire_time;

5.4.存储引擎不能使用索引中范围条件右边的列

1 EXPLAIN SELECT * FROM employees WHERE name= 'LiLei' AND age = 22 AND position ='manager';
2 EXPLAIN SELECT * FROM employees WHERE name= 'LiLei' AND age > 22 AND position ='manager';

5.5.尽量使用覆盖索引（只访问索引的查询（索引列包含查询列）），减少 select * 语句

1 EXPLAIN SELECT name,age FROM employees WHERE name= 'LiLei' AND age = 23 AND position='manager';

1 EXPLAIN SELECT * FROM employees WHERE name= 'LiLei' AND age = 23 AND position ='manager';

5.6.mysql在使用不等于（！=或者<>），not in ，not exists 的时候无法使用索引会导致全表扫描 < 小于、 > 大于、 = 这些，mysql内部优化器会根据检索比例、表大小等多个因素整体评估是否使用索引

1 EXPLAIN SELECT * FROM employees WHERE name != 'LiLei';

5.7.is null,is not null 一般情况下也无法使用索引

1 EXPLAIN SELECT * FROM employees WHERE name is null

5.8.like以通配符开头（'$abc...'）mysql索引失效会变成全表扫描操作

1 EXPLAIN SELECT * FROM employees WHERE name like '%Lei'

1 EXPLAIN SELECT * FROM employees WHERE name like 'Lei%'

问题：解决like'%字符串%'索引不被使用的方法？
a）使用覆盖索引，查询字段必须是建立覆盖索引字段

1 EXPLAIN SELECT name,age,position FROM employees WHERE name like '%Lei%';

b）如果不能使用覆盖索引则可能需要借助搜索引擎

5.9.字符串不加单引号索引失效

1 EXPLAIN SELECT * FROM employees WHERE name = '1000'; 2 EXPLAIN SELECT * FROM employees WHERE name = 1000;

5.10.少用or或in，

用它查询时，mysql不一定使用索引，mysql内部优化器会根据检索比例、表大小等多个因素整体评 估是否使用索引，详见范围查询优化

1 EXPLAIN SELECT * FROM employees WHERE name = 'LiLei' or name = 'HanMeimei';

5.11.范围查询优化 给年龄添加单值索引

1 ALTER TABLE employees ADD INDEX idx_age (age) USING BTREE ;
2 explain select * from employees where age >=1 and age <=2000;

没走索引原因：mysql内部优化器会根据检索比例、表大小等多个因素整体评估是否使用索引。比如这个例子，可能是 由于单次数据量查询过大导致优化器最终选择不走索引 。
优化方法：可以将大的范围拆分成多个小范围。

1 explain select * from employees where age >=1 and age <=1000;
2 explain select * from employees where age >=1001 and age <=2000;

还原最初索引状态

1 ALTER TABLE employees DROP INDEX idx_age;

6、索引使用总结

PS：like KK%相当于=常量，%KK和%KK% 相当于范围

团队曾为一个订单状态显示问题加班至深夜：并非业务逻辑出错，而是前期封装的订单类过度隐藏核心字段，连获取支付时间都需多层调用，最终只能通过反射绕过封装临时解决，后续还需承担潜在风险。这一典型场景，正是 “乱封装” 埋下的隐患 —— 封装本是保障代码安全、提升可维护性的工具，但违背其核心原则的 “乱封装”，反而会让代码从 “易扩展” 走向 “高耦合”，成为开发流程中的阻碍。

一、乱封装的三类典型形态：偏离封装本质的错误实践

乱封装并非 “不封装”，而是未遵循 “最小接口暴露、合理细节隐藏” 原则，表现为三种具体形态，与前文所述的过度封装、虚假封装、混乱封装高度契合，且每一种都直接破坏代码可用性。

1. 过度封装：隐藏必要扩展点，制造使用障碍

为追求 “绝对安全”，将本应开放的核心参数或功能强行隐藏，仅保留僵化接口，导致后续业务需求无法通过正常途径满足。例如某文件上传工具类，将存储路径、上传超时时间等关键参数设为私有且未提供修改接口，仅支持默认配置。当业务需新增 “临时文件单独存储” 场景时，既无法调整路径参数，又不能复用原有工具类，最终只能重构代码，造成开发资源浪费。

反例代码：

// 文件上传工具类（过度封装）

public class FileUploader {

    // 关键参数设为私有且无修改途径

    private String storagePath = "/default/path";

    private int timeout = 3000;

    

    // 仅提供固定逻辑的上传方法，无法修改路径和超时时间

    public boolean upload(File file) {

        // 使用默认storagePath和timeout执行上传

        return doUpload(file, storagePath, timeout);

    }

    

    // 私有方法，外部无法干预

    private boolean doUpload(File file, String path, int time) {

        // 上传逻辑

    }

}

问题：当业务需要 "临时文件存 /tmp 目录" 或 "大文件需延长超时时间" 时，无法通过正常途径修改参数，只能放弃该工具类重新开发。

正确做法：暴露必要的配置接口，隐藏实现细节：

public class FileUploader {

    private String storagePath = "/default/path";

    private int timeout = 3000;

    

    // 提供修改参数的接口

    public void setStoragePath(String path) {

        this.storagePath = path;

    }

    

    public void setTimeout(int timeout) {

        this.timeout = timeout;

    }

    

    // 保留核心功能接口

    public boolean upload(File file) {

        return doUpload(file, storagePath, timeout);

    }

2. 虚假封装：形式化隐藏细节，未实现数据保护

表面通过访问控制修饰符（如private）隐藏变量，也编写getter/setter方法，但未在接口中加入必要校验或逻辑约束，本质与 “直接暴露数据” 无差异，却增加冗余代码。以订单类为例，将orderStatus（订单状态）设为私有后，setOrderStatus()方法未校验状态流转逻辑，允许外部直接将 “已发货” 状态改为 “待支付”，违背业务规则，既未保护数据完整性，也失去了封装的核心价值。

反例代码：

// 订单类（虚假封装）

public class Order {

    private String orderStatus; // 状态：待支付/已支付/已发货

    

    // 无任何校验的set方法

    public void setOrderStatus(String status) {

        this.orderStatus = status;

    }

    

    public String getOrderStatus() {

        return orderStatus;

    }

}



// 外部调用可随意修改状态，违背业务规则

Order order = new Order();

order.setOrderStatus("已发货");

order.setOrderStatus("待支付"); // 非法状态流转，封装未阻止

问题：允许状态从 "已发货" 直接变回 "待支付"，违反业务逻辑，封装未起到数据保护作用，和直接用 public 变量没有本质区别。

正确做法：在接口中加入校验逻辑：

public class Order {

    private String orderStatus;

    

    public void setOrderStatus(String status) {

        // 校验状态流转合法性

        if (!isValidTransition(this.orderStatus, status)) {

            throw new IllegalArgumentException("非法状态变更");

        }

        this.orderStatus = status;

    }

    

    // 隐藏校验逻辑

    private boolean isValidTransition(String oldStatus, String newStatus) {

        // 定义合法的状态流转规则

        return (oldStatus == null && "待支付".equals(newStatus)) ||

               ("待支付".equals(oldStatus) && "已支付".equals(newStatus)) ||

               ("已支付".equals(oldStatus) && "已发货".equals(newStatus));

    }

}

3. 混乱封装：混淆职责边界，堆砌无关逻辑

将多个独立功能模块强行封装至同一类或组件中，未按职责拆分，导致代码耦合度极高。例如某项目的 “CommonUtil” 工具类，同时包含日期转换、字符串处理、支付签名校验三类无关功能，且内部逻辑相互依赖。后续修改支付签名算法时，误触日期转换模块的静态变量，导致多个依赖该工具类的功能异常，排查与修复耗时远超预期。

反例代码：

// 万能工具类（混乱封装）

public class CommonUtil {

    // 日期处理

    public static String formatDate(Date date) { ... }

    

    // 字符串处理

    public static String trim(String str) { ... }

    

    // 支付签名（与工具类无关）

    public static String signPayment(String orderNo, BigDecimal amount) {

        // 使用了类内静态变量，与其他方法产生耦合

        return MD5.encode(orderNo + amount + secretKey);

    }

    

    private static String secretKey = "default_key";

}

问题：当修改支付签名逻辑（如替换加密方式）时，可能误改 secretKey，导致日期格式化、字符串处理等无关功能异常，排查难度极大。

正确做法：按职责拆分封装：

// 日期工具类

public class DateUtil {

    public static String formatDate(Date date) { ... }

}



// 字符串工具类

public class StringUtil {

    public static String trim(String str) { ... }

}



// 支付工具类

public class PaymentUtil {

    private static String secretKey = "default_key";

    public static String signPayment(String orderNo, BigDecimal amount) { ... }

}

二、乱封装的核心危害：从开发效率到系统稳定性的双重冲击

乱封装的危害具有 “隐蔽性” 和 “累积性”，初期可能仅表现为局部开发不便，随业务迭代会逐渐放大，对系统造成多重影响。

1. 降低开发效率，增加需求落地成本

乱封装会导致接口设计与业务需求脱节，当需要调用核心功能或获取关键数据时，需额外编写适配代码，甚至重构原有封装。例如某报表功能需获取订单原始字段用于统计，但前期封装的订单查询接口仅返回加工后的简化数据，无法满足需求，开发团队只能协调原封装者新增接口，沟通与开发周期延长，直接影响项目进度。

2. 破坏系统可扩展性，引发连锁故障

未预留扩展点的乱封装，会让后续功能迭代陷入 “牵一发而动全身” 的困境。某项目的缓存工具类未设计 “缓存过期清除” 开关，当业务需临时禁用缓存时，只能修改工具类源码，却因未考虑其他依赖模块，导致多个功能因缓存逻辑变更而异常，引发线上故障。这种因封装缺陷导致的扩展问题，会随系统复杂度提升而愈发严重。

3. 提升调试难度，延长问题定位周期

内部细节的无序隐藏，会让问题排查失去清晰路径。例如某支付接口返回 “参数错误”，但封装时未在接口中返回具体错误字段，且内部日志缺失关键信息，开发人员需逐层断点调试，才能定位到 “订单号长度超限” 的问题，原本十分钟可解决的故障，耗时延长数倍。

三、避免乱封装的实践原则：回归封装本质，平衡安全与灵活

避免乱封装无需复杂的设计模式，核心是围绕 “职责清晰、接口合理” 展开，结合前文总结的经验，可落地为两大原则。

1. 按 “单一职责” 划分封装边界

一个类或组件仅负责一类核心功能，不堆砌无关逻辑。例如用户模块中，将 “用户注册登录”“信息修改”“地址管理” 拆分为三个独立封装单元，通过明确的接口交互（如用户 ID 关联），避免功能耦合。这种拆分方式既能降低修改风险，也让代码结构更清晰，便于后续维护。

2. 接口设计遵循 “最小必要 + 适度灵活”

• 最小必要：仅暴露外部必须的接口，隐藏内部实现细节（如工具类无需暴露临时变量、辅助函数）；

• 适度灵活：针对潜在变化预留扩展点，避免接口僵化。例如短信发送工具类，核心接口sendSms(String phone, String content)满足基础需求，同时提供setTimeout(int timeout)方法允许调整超时时间，既隐藏签名验证、服务商调用等细节，又能应对不同场景的参数调整需求。

某商品管理项目的封装实践可作参考：商品查询功能同时提供两个接口 —— 面向前端的 “分页筛选简化接口” 和面向后端统计的 “完整字段接口”，既满足不同场景需求，又未暴露数据库查询逻辑，后续数据库表结构调整时，仅需维护内部实现，外部调用无需改动，充分体现了合理封装的价值。

结语

封装的本质是 “用合理的边界保障代码安全，用清晰的接口提升开发效率”，而非 “为封装而封装”。开发过程中，需避免过度追求形式化封装，也需警惕功能堆砌的混乱封装，多从后续维护、业务扩展的角度权衡接口设计。毕竟，好的封装是开发的 “助力”，而非 “阻力”—— 下次封装前，不妨先思考：“这样的设计，会不会给后续埋下隐患？”

员工分页查询功能开发

1. 需求分析

2. 代码开发

1. 根据分页查询接口设计对应的DTO

2. 设计controller层

    @GetMapping("/page")

    @ApiOperation(value = "员工分页查询")

    public Result page(EmployeePageQueryDTO employeePageQueryDTO){

        //输出日志

        log.info("员工分页查询,查询参数: {}",employeePageQueryDTO);

        //调用service层返回分页结果

        PageResult pageResult = employeeService.pageQuery(employeePageQueryDTO);

        //返回result

        return Result.success(pageResult);

    }

3. 设计service层,使用Page Helper进行分页,并返回total和record

 @Override

    public PageResult pageQuery(EmployeePageQueryDTO employeePageQueryDTO) {

        //开始分页

        PageHelper.startPage(employeePageQueryDTO.getPage(), employeePageQueryDTO.getPageSize());



        //调用mapper方法返回page对象,泛型为内容的类型,(page实际是一个List)

        Page page = employeeMapper.pageQuery(employeePageQueryDTO);



        //获取总的数据量

        long total = page.getTotal();



        //获取所有员工对象

        List record = page.getResult();



        //返回结果

        return new PageResult(total,record);

    }

4. 设计Mapper层

    Page pageQuery(EmployeePageQueryDTO employeePageQueryDTO);

4. 使用动态SQL进行查询

<select id="pageQuery" resultType="com.sky.entity.Employee">

        select * from employee

        <where>

            <if test="name != null and name != ''">

                name like concat('%',#{name},'#')

            if>

        where>

        order by create_time desc

    select>

3. 功能测试

Swagger测试:

问题

createTime这种是数组形式传递的

前后端联调:

问题:

操作时间渲染格式问题

4. 代码完善

方式一:

代码:

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")

    private LocalDateTime createTime;



    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")

    private LocalDateTime updateTime;

数据返回:

方式二:

代码:

需要在配置类中重写父类的方法,并配置添加消息转换器

 @Override

    protected void extendMessageConverters(List> converters) {

        log.info("扩展消息转换器");

        //创建一个消息转换器

        MappingJackson2HttpMessageConverter converter  = new MappingJackson2HttpMessageConverter();

        //为消息转换器设置一个对象转换器,对象转换器可以将对象数据转换为json数据

        converter.setObjectMapper(new JacksonObjectMapper());

        //将消息转换器添加到容器中,由于converters内部有很多消息转换器,我们假如的默认排在最后一位

        //所以将顺序设置为最靠前

        converters.add(0,converter);

    }

其中JacksonObjectMapper为自己实现的实体类,写法较为固定

数据返回:

作者：用户4007842211260
来源：juejin.cn/post/7531791862521151528

在 TypeScript（以及 JavaScript）中，迭代器和生成器是用于处理集合数据（如数组、对象等）的强大工具。它们允许你按顺序访问集合中的元素，并提供了一种控制数据访问的方式。

迭代器（Iterator）
迭代器是一个对象，它定义了一个序列，并且提供了一种方法来访问这个序列的元素。迭代器对象实现了 Iterator 接口，该接口要求它有一个 next() 方法。

Iterable 接口
一个对象如果实现了Iterable接口，那么它就是可迭代的。这个接口要求对象必须有一个Symbol.iterator方法，这个方法返回一个迭代器对象。

Iterator 接口
迭代器对象必须实现Iterator接口。这个接口定义了next()方法，该方法返回一个对象，这个对象有两个属性：value和done。value表示当前的元素值，done是一个布尔值，表示是否还有更多的元素可以迭代。

1.可迭代对象（Iterable）

一个对象如果实现了[Symbol.iterator]方法，它就是可迭代的。这个方法必须返回一个迭代器对象。常见的内置可迭代对象包括：Array,String,Map,Set,arguments对象（可通过Array.from()或扩展运算符使用），DOM的NodeList(部分浏览器)。

const arr = [1, 2, 3];

console.log(arr[Symbol.iterator]); 

这些对象之所以能被for...of循环遍历，正是因为它们实现了Symbol.iterator方法。

2.迭代器（Iterator）

迭代器是一个带有next()方法的对象，调用next()返回{value,done}.
value:当前值（当done:true时，value可省略或为undefined）
done:布尔值，表示是否遍历完成。

const arr = [10, 20];

const iterator = arr[Symbol.iterator]();



console.log(iterator.next());

console.log(iterator.next());

console.log(iterator.next());

注意：迭代器本身通常也是可迭代的（即它自己也有[Symbol.iterator()]）,这样它就可以用于for...of。

3.for...of与展开运算符的工作原理

for (const item of [1, 2, 3]) {

  console.log(item);

}

背后的逻辑：

• 获取[1,2,3] [Symbol.iterator]()


• 不断调用.next()直到done:true

同理：

const str = "hi";

const chars = [...str];

console.log(chars)

手动实现一个可迭代对象

class Countdown {

  constructor(private start: number) {}



  [Symbol.iterator](): Iterator<number> {

    let current = this.start;

    return {

      next(): { value: number; done: boolean } {

        if (current < 0) {

          return { value: undefined, done: true };

        }

        return { value: current--, done: false };

      },

      // 可选：支持 return() 方法用于提前终止（如 break）

      return() {

        console.log("迭代被中断");

        return { value: undefined, done: true };

      }

    };

  }

}



// 使用

const countdown = new Countdown(3);

for (const n of countdown) {

  console.log(n); 

}

生成器（Generator）:简化迭代器创建

生成器函数是创建迭代器的便捷方式。使用function* 定义，内部用yield暂停执行。

function* idGenerator() {

  let id = 1;

  while (true) {

    yield id++;

  }

}



const gen = idGenerator();

console.log(gen.next().value);

console.log(gen.next().value);

生成器函数返回一个生成器对象，它即是迭代器，也是可迭代对象。

你甚至可以让一个对象使用生成器作为[Symbol.iterator]

const myRange = {

  from: 1,

  to: 5,

  *[Symbol.iterator]() {

    for (let i = this.from; i <= this.to; i++) {

      yield i;

    }

  }

};



console.log([...myRange]);

迭代器协议总结：

协议：Iterable

方法：[Symbol.iterator]():Iterator

返回值：迭代器对象

说明：表示可被遍历

协议：Iterator

方法：next():{value,done}

返回值：状态对象

说明：提供下一个值

协议：可选

方法：return?():{value,done}

返回值：状态对象

说明：处理提前退出

协议：可选

方法：throw?():{value,done}

返回值：状态对象

说明：处理异常抛出

大家好，我是潘Sir，持续分享IT技术，帮你少走弯路。《鸿蒙应用开发从入门到项目实战》系列文章持续更新中，陆续更新AI+编程、企业级项目实战等原创内容、欢迎关注！

ArkUI提供了丰富的系统组件，用于制作鸿蒙原生应用APP的UI，本文主要讲解文本组件Text和TextInput的使用。

一、文本Text

1.1 概述

Text为文本组件，用于显示文字内容。

1.2 参数

Text组件的参数类型为string | Resource，下面分别对两个参数类型进行介绍：

• string类型

Text('我是一段文本')

• Resource 类型

Resource类型的参数用于引用 resources/*/element目录中定义的字符串，同样需要使用$r()引用。

例如resources/base/element目录中有一个string.json文件，内容如下

{

  "string": [

    {

      "name": "greeting",

      "value": "你好"

    }

  ]

}

此时我们便可通过如下方式引用并显示greeting的内容。

Text($r('app.string.greeting'))

示例代码：

1、分别在resources下的base、en_US、zh_CN目录下的element下的string.json中添加对应的配置

在base和zh_CN下的element下的string.json中添加

 {

      "name": "greeting",

      "value": "你好,鸿蒙"

    }

在en_US目录下的element下的string.json中添加

{

      "name": "greeting",

      "value": "hello,harmony"

    }

2、component目录下新建text目录，新建TextParameterPage.ets文件

@Entry

@Component

// text组件

struct TextParameterPage {

  build() {

    Column({ space: 50 }) {

      // text组件参数

      //1、字符串类型

      Text('你好,鸿蒙')

        .fontSize(50)

​

      //2、Resource类型

      Text($r('app.string.greeting'))

        .fontSize(50)

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

1.3 常用属性

1.3.1 字体大小

字体大小可通过fontSize()方法进行设置，该方法的参数类型为string | number| Resource，下面逐一介绍

• string类型

string类型的参数可用于指定字体大小的具体单位，例如fontSize('100px')，字体大小的单位支持px、fp。其中fp(font pixel)与vp类似，具体大小也会随屏幕的像素密度变化而变化。

• number类型

number类型的参数，默认以fp作为单位。

• Resource类型

Resource类型参数用于引用resources下的element目录中定义的数值。

示例代码：

在component/text目录下新建FontSizePage.ets文件

@Entry

@Component

// text属性：字体大小

struct FontSizePage {

  build() {

      Column({ space: 50 }) {

        // 1、参数为string类型

        Text('你好,鸿蒙')

          .fontSize('150px')

​

        Text('你好,鸿蒙')

          .fontSize('50fp')

​

        // 2、参数为number类型

        Text('你好,鸿蒙')

          .fontSize(50)

      }.width('100%')

      .height('100%')

      .justifyContent(FlexAlign.Center)

  }

}

1.3.2 字体粗细

字体粗细可通过fontWeight()方法进行设置，该方法参数类型为number | FontWeight | string，下面逐一介绍

• number类型

number类型的取值范围是[100,900]，取值间隔为100，默认为400，取值越大，字体越粗。

• FontWeight类型

FontWeight为枚举类型，可选枚举值如下

• string类型

string类型的参数仅支持number类型和FontWeight类型参数的字符串形式，例如例如'100'和bold。

示例代码：

在component/text下新建FontWeightPage.ets文件

@Entry

@Component

// 字体粗细

struct FontWeightPage {

​

  build() {

    Column({ space: 50 }) {

​

      //默认效果

      Text('你好,鸿蒙')

        .fontSize(50)

​

      // 1、number类型

      Text('你好,鸿蒙')

        .fontSize(50)

        .fontWeight(666)

​

      // 2、FontWeight类型

      Text('你好,鸿蒙')

        .fontSize(50)

        .fontWeight(FontWeight.Lighter)

​

      // 3、string类型

      Text('你好,鸿蒙')

        .fontSize(50)

        .fontWeight('800')

​

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

1.3.3 字体颜色

字体颜色可通过fontColor()方法进行设置，该方法参数类型为Color | string | number | Resource，下面逐一介绍

• Color类型
  
  

  Color为枚举类型，其中包含了多种常用颜色，例如Color.Green



• string类型
  
  

  string类型的参数可用于设置 rgb 格式的颜色，具体写法可以为'rgb(0, 128, 0)'或者'#008000'



• number类型
  
  

  number类型的参数用于使用16进制的数字设置 rgb 格式的颜色，具体写法为0x008000



• Resource类型
  
  

  Resource类型的参数用于应用resources下的element目录中定义的值。

示例代码：

在component/text目录下新建FontColorPage.ets文件

@Entry

@Component

// 字体颜色

struct FontColorPage {

​

  build() {

    Column({ space: 50 }) {

      // 1、Color类型

      Text('Color.Green')

        .fontSize(40)

        .fontWeight(FontWeight.Bold)

        .fontColor(Color.Green)

​

      // 2、string类型

      Text('rgb(0, 128, 0)')

        .fontSize(40)

        .fontWeight(FontWeight.Bold)

        .fontColor('rgba(59, 171, 59, 0.33)')

​

      Text('#008000')

        .fontSize(40)

        .fontWeight(FontWeight.Bold)

        .fontColor('#a4008000')

​

      // 3、number类型

      Text('0x008000')

        .fontSize(40)

        .fontWeight(FontWeight.Bold)

        .fontColor(0xa4008000)

​

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

1.3.4 文本对齐

文本对齐方向可通过textAlign()方法进行设置，该方法的参数为枚举类型TextAlign，可选的枚举值如下

各选项效果如下

示例代码：

text目录下新建TextAlignPage.ets文件

@Entry

@Component

// 文本对齐

struct TextAlignPage {

​

  build() {

    Row() {

      Column({ space: 50 }) {

        Column({ space: 10 }) {

          // 1、TextAlign.Start

          Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

            .fontSize(20)

            .width(300)

            .borderWidth(1)

            .textAlign(TextAlign.Start)

          Text('Start')

        }

​

        Column({ space: 10 }) {

          // 2、TextAlign.Center

          Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

            .fontSize(20)

            .width(300)

            .borderWidth(1)

            .textAlign(TextAlign.Center)

          Text('Center')

        }

​

        Column({ space: 10 }) {

          // 3、TextAlign.End

          Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

            .fontSize(20)

            .width(300)

            .borderWidth(1)

            .textAlign(TextAlign.End)

          Text('End')

        }

​

      }.width('100%')

      .height('100%')

      .justifyContent(FlexAlign.Center)

    }

  }

}

1.3.5 最大行数和超长处理

可使用maxLines()方法控制文本的最大行数，当内容超出最大行数时，可使用textOverflow()方法处理超出部分，该方法的参数类型为{ overflow: TextOverflow }，其中TextOverflow为枚举类型，可用枚举值有

各选项效果如下

示例代码：

在component/text目录下新建TextOverFlowPage.ets文件

@Entry

@Component

// 最大行数和超长处理

struct TextOverFlowPage {

​

  build() {

    Column({ space: 50 }) {

      Column({ space: 10 }) {

        Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

          .fontSize(20)

          .width(300)

          .borderWidth(1)

        Text('原始内容')

      }

​

      // 1、TextOverflow.Clip 文本超长时，进行裁剪显示

      Column({ space: 10 }) {

        Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

          .fontSize(20)

          .width(300)

          .borderWidth(1)

          .maxLines(2)

          .textOverflow({ overflow: TextOverflow.Clip })

        Text('Clip')

      }

​

      // 2、TextOverflow.Ellipsis 文本超长时，显示不下的文本用省略号代替

      Column({space:10}) {

        Text('鸿蒙操作系统是由华为公司开发的全场景、分布式的新一代操作系统，旨在实现各类智能设备的高效协同工作和统一体验')

          .fontSize(20)

          .width(300)

          .borderWidth(1)

          .maxLines(2)

          .textOverflow({ overflow: TextOverflow.Ellipsis })

        Text('Ellipsis')

      }

​

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

二、文本输入TextInput

2.1 概述

TextInput为文本输入组件，用于接收用户输入的文本内容。

2.2 参数

TextInput组件的参数定义如下

TextInput(value?:{placeholder?: string|Resource , text?: string|Resource})

• placeholder

placeholder属性用于设置无输入时的提示文本，效果如下

• text

text用于设置输入框当前的文本内容，效果如下

示例代码：

component目录下新建input目录，新建TextInputParameter.ets文件

@Entry

@Component

// 文本输入参数

struct TextInputParameter {

​

  build() {

    Column({ space: 50 }) {

      TextInput()

        .width('70%')

​

      // 1、placeholder参数

      TextInput({ placeholder: '请输入用户名' })

        .width('70%')

​

      // 2、text参数

      TextInput({ text: '当前内容' })

        .width('70%')

​

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

2.3 常用属性

2.3.1 输入框类型

可通过type()方法设置输入框的类型，该方法的参数为InputType枚举类型，可选的枚举值有

2.3.2 光标样式

可通过caretColor()方法设置光标的颜色，效果如下

2.3.3 placeholder样式

可通过placeholderFont()和placeholderColor()方法设置 placeholder 的样式，其中placeholderFont()用于设置字体，包括字体大小、字体粗细等，placeholderColor()用于设置字体颜色，效果如下

2.3.4 文本样式

输入文本的样式可通过fontSize()、fontWeight()、fontColor()等通用属性方法进行设置。

示例代码：

在input目录下新建TextInputAttributePage.ets文件

@Entry

@Component

// TextInput属性

struct TextInputAttributePage {



  build() {

    Column({ space: 50 }) {



      // 1、输入框类型 type()设置类型， InputType

      Column({ space: 10 }) {

        Text('输入框类型')

        TextInput({ placeholder: '请输入任意内容' })

          .width('70%')

          .type(InputType.Normal)

        TextInput({ placeholder: '请输入数字' })

          .width('70%')

          .type(InputType.Number)

        TextInput({ placeholder: '请输入密码' })

          .width('70%')

          .type(InputType.Password)

      }



      // 2、光标样式 caretColor()设置光标的颜色

      Column({ space: 10 }) {

        Text('光标样式')

        TextInput()

          .width('70%')

          .caretColor(Color.Red)

      }



      // 3、placeholder样式 placeholderFont、placeholderColor

      Column({ space: 10 }) {

        Text('placeholder样式')

        TextInput({ placeholder: '请输入用户名' })

          .width('70%')

          .placeholderFont({ weight: 800 ,style:FontStyle.Italic})

          .placeholderColor('#66008000')

      }



    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

2.4 常用事件

2.4.1 change事件

每当输入的内容发生变化，就会触发 change 事件，开发者可使用onChange()方法为TextInput组件绑定 change 事件，该方法的参数定义如下

onChange(callback: (value: string) => void)

其中value为最新内容。

2.4.2 焦点事件

焦点事件包括获得焦点和失去焦点两个事件，当输入框获得焦点时，会触发 focus 事件，失去焦点时，会触发 blur 事件，开发者可使用onFocus()和onBlur()方法为 TextInput 组件绑定相关事件，两个方法的参数定义如下

onFocus(event: () => void)	

onBlur(event: () => void)

示例代码：

在input目录下新建TextInputEvent.ets文件

@Entry

@Component

// TextInput事件

struct TextInputEvent {



  build() {

    Column({ space: 50 }) {

      TextInput({ placeholder: '请输入用户名' })

        .width('70%')

        .type(InputType.Normal)

        // 1、change事件

        .onChange((value) => {

          console.log(`用户名:${value}`)

        })

        // 2、获得焦点

        .onFocus(() => {

          console.log('用户名输入框获得焦点')

        })

        // 3、失去焦点

        .onBlur(() => {

          console.log('用户名输入框失去焦点')

        })



      TextInput({ placeholder: '请输入密码' })

        .width('70%')

        .type(InputType.Password)

        .onChange((value) => {

          console.log(`密码:${value}`)

        })

        .onFocus(() => {

          console.log('密码输入框获得焦点')

        })

        .onBlur(() => {

          console.log('密码输入框失去焦点')

        })

    }.width('100%')

    .height('100%')

    .justifyContent(FlexAlign.Center)

  }

}

《鸿蒙应用开发从入门到项目实战》系列文章持续更新中，陆续更新AI+编程、企业级项目实战等原创内容，防止迷路，欢迎关注！

先前在使用豆包的Web版时，发现在“帮我写作”模块中用以输入Prompt的模板输入框非常实用，既可以保留模板输入的优势，来调优指定的写作方向，又能够不失灵活地自由编辑。其新对话的输入交互也非常细节，例如选择“音乐生成”后技能提示本身也是编辑器的嵌入模块，不可以直接删除。

虽然看起来这仅仅是一个文本内容的输入框，但是实现起来并不是那么容易，细节的交互也非常重要。例如技能提示节点直接作为输入框本身模块，多行文本就可以在提示下方排版，而不是类似网格布局需要在左侧留空白内容。那么在这里我们就以豆包的交互为例，来实现Prompt的变量模板输入框。

概述

当我们开发AI相关的应用时，一个常见的场景便是需要用户输入Prompt，或者是在管理后台维护Prompt模板提供给其他用户使用。此时我们就需要一个能够支持内容输入或者模板变量的输入框，那么常见的实现方式有以下几种:

• 纯文本输入框，类似于<input>、<textarea>等标签，在其DOM结构周围实现诸如图片、工具选择等按钮的交互。


• 表单变量模板，类似于填空的形式，将Prompt模板以表单的形式填充变量，用户只需要填充所需要的变量内容即可。


• 变量模板输入框，同样类似于填空的形式，但是其他内容也是可以编辑的，以此实现模版变量调优以及灵活的自由指令。

在这里有个有趣的事情，豆包的这个模板输入框是用slate做的，而后边生成文档的部分却又引入了新的富文本框架。也就是其启用分步骤“文档编辑器”模式的编辑器框架与模板输入框的编辑器框架并非同一套实现，毕竟引入多套编辑器还是会对应用的体积还是有比较大的影响。

因此为什么不直接使用同一套实现则是非常有趣的问题，虽然一开始可能是想着不同的业务组实现有着不同的框架选型倾向。但是仔细研究一下，想起来slate对于inline节点是特殊类型实现，其内嵌的inline左右是还可以放光标的，重点是inline内部也可以放光标。

这个问题非常重要，如果不能实现空结构的光标位置，那么就很难实现独立的块结构。而这里的实现跟数据结构和选区模式设计非常相关，若是针对连续的两个DOM节点位置，如果需要实现多个选区位置，就必须有足够的选区表达，而如果是纯线性的结构则无法表示。

// <em>text</em><strong>text</strong>



// 完全匹配 DOM 结构的设计

{ path: [0], offset: 4 } // 位置 1

{ path: [1], offset: 0 } // 位置 2



// 线性结构的设计

{ offset: 4 } // 位置 1

对于类似的光标位置问题，开源的编辑器编辑器例如Quill、Lexical等，甚至商业化的飞书文档、Notion都没有直接支持这种模式。这些编辑器的schema设计都是两个字符间仅会存在一个caret的光标插入点，验证起来也很简单，只要看能否单独插入一个空内容的inline节点即可。

在这里虽然我们主要目标是实现变量模板的输入框形式，但是其他的形式也非常有意思，例如GitHub的搜索输入框高亮、CozeLoop的Prompt变量调时输入等。因此我们会先将这些形式都简单叙述一下，在最后再重点实现变量模板输入框的形式，最终的实现可以参考 BlockKit Variables 以及 CodeSandbox。

纯文本输入框

纯文本输入框的形式就比较常见了，例如<input>、<textarea>等标签，当前我们平时使用的输入框也都是类似的形式，例如DeepSeek就是单纯的textarea标签。当然也有富文本编辑器的输入框形式，例如Gemini的输入框，但整体形式上基本一致。

文本 Input

单纯的文本输入框的形式自然是最简单的实现了，直接使用textarea标签即可，只不过这里需要实现一些控制形式，例如自动计算文本高度等。此外还需要根据业务需求实现一些额外的交互，例如图片上传、联网搜索、文件引用、深度思考等。

+-------------------------------------------+

|                                           |

| DeepThink   Search                      ↑ |

+-------------------------------------------+

文本高亮匹配

在这里更有趣的是GitHub的搜索输入框，在使用综合搜索、issue搜索等功能时，我们可以看到如果关键词不会会被高亮。例如is:issue state:open 时，issue和open会被高亮，而F12检查时发现其仅是使用input标签，并没有引入富文本编辑器。

在这里GitHub的实现方式就非常有趣，实际上是使用了div渲染格式样式，来实现高亮的效果，然后使用透明的input标签来实现输入交互。如果在F12检查时将input节点的color透明隐藏掉，就可以发现文本的内容重叠了起来，需要关注的点在于怎么用CSS实现文本的对齐。

我们也可以实现一个类似的效果，主要关注字体、spacing的文本对齐，以及避免对浮层的事件响应，否则会导致鼠标点击落到浮层div而不是input导致无法输入。其实这里还有一些其他的细节需要处理，例如可能存在滚动条的情况，不过在这里由于篇幅问题我们就不处理了。

<div class="container">

  <div id="$$1" class="overlay"></div>

  <input id="$$2" type="text" class="input" value="变量文本{{vars}}内容" />

</div>

<script>

    const onInput = () => {

      const text = $$2.value;

      const html = text.replace(/{{(.*?)}}/g, `<span style="color: blue;">{{$1}}</span>`);

      $$1.innerHTML = html;

    };

    $$2.oninput = onInput;

    onInput();

</script>

<style>

  .container { position: relative; height: 30px; width: 800px; border: 1px solid #aaa; border-radius: 3px; }

  .container > * { width: 800px; height: 30px; font-size: 16px; box-sizing: border-box; font-family: inherit;  }

  .overlay { pointer-events: none; position: absolute; left: 0; top: 0; height: 100%; width: 100%; }

  .overlay { white-space: pre; display: flex; align-items: center; word-break: break-word; }

  .input { padding: 0; border-width: 0; word-spacing: 0; letter-spacing: 0; color: #0000; caret-color: #000; }

</style>

表单变量模板

变量模板的形式非常类似于表单的形式，在有具体固定的Prompt模板或者具体的任务时，这种模式非常合适。还有个有意思的事情，这种形式同样适用于非AI能力的渐进式迭代，例如文档场景常见的翻译能力，原有的交互形式是提交翻译表单任务，而在这里可以将表单形式转变为Prompt模板来使用。

表单模板

表单模版的交互形式比较简单，通常都是左侧部分编写纯文本并且预留变量空位，右侧部分会根据文本内容动态构建表单，CozeLoop中有类似的实现形式。除了常规的表单提交以外，将这种交互形式融入到LLms融入到流程编排中实现流水线，以提供给其他用户使用，也是常见的场景。

此外，表单模版适用于比较长的Prompt模版场景，从易用性上来说，用户可以非常容易地专注变量内容的填充，而无需仔细阅读提供的Prompt模版。并且这种形式还可以实现变量的复用，也就是在多个位置使用同一个变量。

+--------------------------------------------------+------------------------+

| 请帮我写一篇关于 {{topic}} 的文章，文章内容要          | 主题: ________________ |

| 包含以下要点: {{points}}，文章风格符合 {{style}}，    | 要点: ________________ |

| 文章篇幅为 {{length}}，并且要包含一个吸引人的标题。     | 风格: ________________ |

|                                                  | 长度: ________________ |

+--------------------------------------------------+------------------------+

行内变量块

行内变量块就相当于内容填空的形式，相较表单模版来说，行内变量块则会更加倾向较短的Prompt模板。整个Prompt模板绘作为整体，而变量块则作为行内的独立块结构存在，用户可以直接点击变量块进行内容编辑，注意此处的内容是仅允许编辑变量块的内容，模板的文本是不能编辑的。

+---------------------------------------------------------------------------+

| 请帮我写一篇关于 {{topic}} 的文章，文章内容要包含以下要点: {{points}}，           |

| 文章风格符合 {{style}}，文章篇幅为 {{length}}，并且要包含一个吸引人的标题。        |

+---------------------------------------------------------------------------+

这里相对豆包的变量模板输入框形式来说，最大的差异就是非变量块不可编辑。那么相对来说这种形式就比较简单了，普通的文本就使用span节点，变量节点则使用可编辑的input标签即可。看起来没什么问题，然而我们需要处理其自动宽度，类似arco的实现，否则交互起来效果会比较差。

实际上input的自动宽度并没有那么好实现，通常来说这种情况需要额外的div节点放置文本来同步计算宽度，类似于前文我们聊的GitHub搜索输入框的实现方式。那么在这里我们使用Editable的span节点来实现内容的编辑，当然也会存在其他问题需要处理，例如避免回车、粘贴等。

<div id="$$0" class="container"><span>请帮我写一篇关于</span><span class="input" placeholder="{{topic}}" ></span><span>的文章，文章内容要包含以下要点:</span><span class="input" placeholder="{{points}}" ></span>，<span>文章风格符合</span><span class="input" placeholder="{{style}}" ></span><span>，文章篇幅为</span><span class="input" placeholder="{{length}}" ></span><span>，并且要包含一个吸引人的标题。</span></div>

<style>

  .container > * { font-size: 16px; display: inline-block; }

  .input { outline: none; margin: 3px 2px; border-radius: 4px; padding: 2px 5px; }

  .input { color: #0057ff; background: rgba(0, 102, 255, 0.06); }

  .input::after { content: attr(data-placeholder); cursor: text; opacity: 0.5; pointer-events: none;  }

</style>

<script>

  const inputs = document.querySelectorAll(".input");

  inputs.forEach(input => {

    input.setAttribute("contenteditable", "true");

    const onInput = () => {

      !input.innerText ? input.setAttribute("data-placeholder", input.getAttribute("placeholder"))

      : input.removeAttribute("data-placeholder");

    }

    onInput();

    input.oninput = onInput;

  });

</script>

变量模板输入框

变量模板输入框可以认为是上述实现的扩展，主要是支持了文本的编辑，这种情况下通常就需要引入富文本编辑器来实现了。因此，这种模式同样适用于较短的Prompt模版场景，并且用户可以在模板的基础上进行灵活的调整，参考下面的示例实现的 DEMO 效果。

+---------------------------------------------------------------------------+

| 我是一位 {{role}}，帮我写一篇关于 {{theme}} 内容的 {{platform}} 文章，          |

| 需要符合该平台写作风格，文章篇幅为 {{space}} 。                                 |

+---------------------------------------------------------------------------+

方案设计

实际上只要涉及到编辑器相关的内容，无论是富文本编辑器、图形编辑器等，都会比较复杂，其中的都涉及到了数据结构、选区模式、渲染性能等问题。而即使是个简单的输入框，也会涉及到其中的很多问题，因此我们必须要做好调研并且设计好方案。

开篇我们就讲述了为何slate可以实现这种交互，而其他的编辑器框架则不行，主要是因为slate的inline节点是特殊类型实现。具体来说，slate的inline节点是一个children数组，因此这里看起来是同个位置的选区可以通过path的不同区分，child内会多一层级。

[

  {

    type: "paragraph",

    children: [{

      type: "badge",

      children: [{ text: "Approved" }],

    }],

  },

]

因此既然slate本身设计上支持这种选区行为，那么实现起来就会非常方便了。然而我对于slate编辑器实在是太熟悉了，也为slate提过一些PR，所以在这里我并不太想继续用slate实现，而恰好我一直在写 从零实现富文本编辑器 的系列文章，因此用自己做的框架BlockKit实现是个不错的选择。

而实际上，用slate的实现并非完全没有问题，主要是slate的数据结构完全支持任意层级的嵌套，那么也就是说，我们必须要用很多策略来限制用户的行为。例如我们复制了嵌入节点，是完全可以将其贴入到其他块结构内，造成更多级别的children嵌套，类似这种情况必须要写完善的normalize方法处理。

那么在BlockKit中并不支持多层级的嵌套，因为我们的选区设计是线性的结构，即使有多个标签并列，大多数情况下我们会认为选区是在偏左的DOM节点末尾。而由于某些情况下节点在浏览器中的特殊表现，例如Embed类型的节点，我们才会将光标放置在偏右的DOM位置。

// 左偏选区设计

{ offset: 4 }

// <em>text[caret]</em><strong>text</strong>

{ offset: 5 }

// <em>text</em><strong>t[caret]ext</strong>

因此我们必须要想办法支持这个行为，而更改架构设计则是不可行的，毕竟如果需要修改诸如选区模式、数据结构等模块，就相当于修改了地基，上层的所有模块都需要重新适配。因此我们需要通过其他方式来实现这个功能，而且还需要在整体编辑器的架构设计基础上实现。

那么这里的本质问题是我们的编辑器不支持独立的空结构，其中主要是没有办法额外表示一个选区位置，如果能够通过某些方式独立表达选区位置，理论上就可以实现这个功能。沿着这个思路，我们可以比较容易地想出来下面的两个方式:

方案1的优点是其本身并不会脱离编辑器的控制，整体的选区、历史记录等操作都可以被编辑器本身管理。缺点是需要额外维护Embed节点，整体实现会比较复杂，例如删除末尾Embed节点时需要配对删除前方的节点、粘贴的时候也需要避免节点被重复插入、需要额外的包装节点处理样式等。

方案2的优点是维护了独立的节点，在DOM层面上不需要额外的处理，将其作为普通可编辑的Embed节点即可。缺点是脱离了编辑器框架本身的控制，必须要额外处理选区、历史记录等操作，相当于本身实现了内部的不受控的新编辑器，独立出来的编辑区域自然需要额外的Case需要处理。

最终比较起来，我们还是选择了方案2，主要是其实现起来会比较简单，并且不需要额外维护复杂的约定式节点结构。虽然脱离了编辑器本身的控制，但是我们可以通过事件将其选区、历史记录等操作同步到编辑器本身，相当于半受控处理，虽然会有一些边界情况需要处理，但是整体实现起来还比较可控。

Editable 组件

那么在方案2的基础上，我们就首先需要实现一个Editable组件，来实现变量块的内容编辑。由于变量块的内容并不需要支持任何加粗等操作，因此这里我们并不需要嵌套富文本编辑器本身，而是只需要支持一个纯文本的可编辑区域即可，通过事件通信的形式实现半受控处理。

因此在这里我们就只需要一个span标签，并且设置其contenteditable属性为true即可。至于为什么不使用input来实现文本的输入框，主要是input的宽度跟随文本长度变化需要自己测量，而直接使用可编辑的span标签是天然支持的。

<div

  className="block-kit-editable-text"

  contentEditable

  suppressContentEditableWarning

></div>

可输入的变量框就简单地实现出来了，而仅仅是可以输入文本并不够，我们还需要空内容时的占位符。由于Editable节点本身并不支持placeholder属性，因此我们必须要自行注入DOM节点，而且还需要避免占位符节点被选中、复制等，这种情况下伪元素是最合适的选择。

.block-kit-editable-text {

  display: inline-block;

  outline: none;



  &::after {

    content: attr(data-vars-placeholder);

    cursor: text;

    opacity: 0.5;

    pointer-events: none;

    user-select: none;

  }

}

当然placeholder的值可以是动态设置的，并且placeholder也仅仅是在内容为空时才会显示，因此我们还需要监听input事件来动态设置data-vars-placeholder属性。

const showPlaceholder = !value && placeholder && !isComposing;

<div

  className="block-kit-editable-text"

  data-vars-placeholder={showPlaceholder ? placeholder : void 0}

></div>

这里的isComposing状态可以注意一下，这个状态是用来处理输入法IME的。当唤醒输入法输入的时候，编辑器通常会处于一个不受控的状态，这点我们先前在处理输入的文章中讨论过，然而此时文本区域是存在候选词的，因此这个情况下不应该显示占位符。

const [isComposing, setIsComposing] = useState(false);

const onCompositionStart = useMemoFn(() => {

  setIsComposing(true);

});



const onCompositionEnd = useMemoFn((e: CompositionEvent) => {

  setIsComposing(false);

});

接下来需要处理内容的输入，在此处的半受控主要是指的我们并不依靠BeforeInput事件来阻止用户输入，而是在允许用户输入后，主动通过onChange事件将内容同步到外部。而外部编辑器接收到变更后，会触发该节点的rerender，在这里我们再检查内容是否一致决定更新行为。

在这里不使用input标签其实也会存在一些问题，主要是DOM标签本身内部是可以写入很多复杂的HTML内容的，而这里我们是希望将其仅仅作为普通的文本输入框来使用，因此我们在检查到DOM节点不符合要求的时候，需要将其重置为纯文本内容。

useEffect(() => {

  if (!editNode) return void 0;

  if (isDOMText(editNode.firstChild)) {

    if (editNode.firstChild.nodeValue !== props.value) {

      editNode.firstChild.nodeValue = props.value;

    }

    for (let i = 1, len = editNode.childNodes.length; i < len; i++) {

      const child = editNode.childNodes[i];

      child && child.remove();

    }

  } else {

    editNode.innerText = props.value;

  }

}, [props.value, editNode]);



const onInput = useMemoFn((e: InputEvent) => {

  if (e.isComposing || isNil(editNode)) {

    return void 0;

  }

  const newValue = editNode.textContent || "";

  newValue !== value && onChange(newValue);

});

对于避免Editable节点出现非文本的HTML内容，我们还需要在onPaste事件中阻止用户粘贴非文本内容，这里需要阻止默认行为，并且将纯文本的内容提取出来重新插入。这里还涉及到了使用旧版的浏览器API，实际上L0的编辑器就是基于这些旧版的浏览器API实现的，例如pell编辑器。