# very-util-lang

**Repository Path**: mefaso/very-util-lang

## Basic Information

- **Project Name**: very-util-lang
- **Description**: 一个古老的scala工具库
- **Primary Language**: Scala
- **License**: Not specified
- **Default Branch**: 重构
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2014-02-01
- **Last Updated**: 2025-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# very-util-lang

**版本**: 0.0.8  
**组织**: ws

## 项目概述

`very-util-lang` 是一个多功能工具库，集成了 Scala 与 Java 的多种常用工具和框架，主要功能包括：

- **实用工具**：数组、集合、Map 与字符串的辅助操作（见 Java 源码中的 ArrayUtils、Colls、Maps、Strs）。
- **依赖注入 (DI) 与 AOP**：提供一个简单的依赖注入容器和面向切面编程支持，包含模块注册、模块获取、动态代理拦截等（见 `ws.very.util.di` 包）。
- **动态脚本执行**：集成 Ammonite REPL，可用于动态执行 Scala 代码以及脚本热加载（见 `ws.very.util.amm` 包）。
- **数据压缩**：基于 Apache Commons Compress 实现 LZ4 块压缩与解压功能（见 `ws.very.util.compress.Lz4`）。
- **表达式语言 (ELS)**：通过 DSL 构造条件表达式，支持组合 And、Or、相等比较以及专门的字符串和数字条件（见 `ws.very.util.el.Els`）。
- **会话管理**：采用 `TransmittableThreadLocal` 实现多线程环境下的会话层级管理（见 `ws.very.util.di.Session`）。

此外，项目支持 Scala 3（版本 3.3.3），并在 `scala3fix` 目录中包含了部分迁移辅助代码。

## 详细文档

更多详细内容请参阅 docs 目录中的文档。

## 文件结构

```
very-util-lang/
│
├── .gitignore               // 忽略构建生成文件、IDE 配置等
├── build.sbt                // 项目的 SBT 构建配置，定义 Scala 版本、编译选项及依赖库
├── project/
│   ├── .gitignore
│   ├── build.properties     // SBT 版本配置
│   └── plugins.sbt          // SBT 插件配置（依赖树、Scala3 迁移、显式依赖检查）
├── scala3fix/               // Scala 3 补充与迁移代码，如泛型辅助类型
│   ├── build.sbt
│   └── src/main/scala/ws/very/util/generic/Generic.scala
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── ws/very/util/
│   │   │       ├── lang/
│   │   │       │   ├── ArrayUtils.java     // 数组操作工具
│   │   │       │   ├── Colls.java          // 集合操作工具
│   │   │       │   ├── Maps.java           // Map 辅助函数，如 getOrDefault
│   │   │       │   └── Strs.java           // 字符串拼接工具
│   │   │       └── di/
│   │   │           └── BeVal.java          // 标记注解，用于 DI/代理相关
│   │   └── scala/
│   │       ├── di/                         // 依赖注入及 AOP 相关实现
│   │       │   ├── AOP.scala               // 动态代理与切面拦截机制
│   │       │   ├── DI.scala                // DI 容器实现及模块注册
│   │       │   ├── Proxy.scala             // 代理构建、代码生成支持
│   │       │   ├── Session.scala           // 会话层管理（基于 TransmittableThreadLocal）
│   │       │   └── package.scala           // DI 相关包级定义
│   │       ├── amm/                        // Ammonite REPL 集成与动态脚本执行
│   │       │   └── AmmoniteBridge.scala
│   │       ├── compress/                   // LZ4 数据压缩工具
│   │       │   └── Lz4.scala
│   │       ├── el/                        // 表达式语言构造，如条件与逻辑组合
│   │       │   └── Els.scala
│   │       ├── init/                      // 系统初始化配置，模块注册入口
│   │       │   └── SysConf.scala
│   │       └── scala/
│   │           └── Serializable.scala     // 自定义序列化 trait，用于旧库兼容
└── ...
```

## 主要模块详解

### 1. 工具函数库（Java 部分）

- **ArrayUtils.java**  
  提供数组是否为空的静态方法，简化非空检查。

- **Colls.java**  
  包含创建空集合和判断 Iterable 对象是否为空的方法。

- **Maps.java**  
  扩展了 Map 的功能，提供 `getOrDefault` 和 `getOrUpdate` 方法，用以简化常见 Map 操作。

- **Strs.java**  
  封装字符串拼接功能，利用 `StringBuilder` 实现高效字符串构造操作。

### 2. 依赖注入与 AOP（`ws.very.util.di`）

- **模块注册与获取**  
  通过 `DIModule` 与 `ModuleDef`（分别定义在 DI.scala 与 ModuleDef 中）实现简单的依赖注入容器，支持根据环境变量 `DiMode`（或 `DiMode-<接口名称>`）确定加载的模块实现。例如，在系统初始化 `SysConf.scala` 中注册了日志模块与表格模块：
  ```scala
  def modules = Seq(
    ModuleDef.by[LogModule](new log.DebugConsoleModule),
    ModuleDef.by[TableModule](new TableModule)
  )
  ```
  调用 `DI[LogModule]` 即可获取已注册的日志模块实例。

- **AOP 与代理**  
  在 `AOP.scala` 中定义了 `InvocationContext` 接口及其实现，支持通过动态代理拦截方法调用，便于日后拓展 AOP 功能。

- **会话管理**  
  `Session.scala` 实现了基于 `TransmittableThreadLocal` 的会话层级管理机制，提供了进入、退出、层级传递等操作，适应多线程环境下的上下文绑定需求。

### 3. 动态脚本执行（Ammonite 集成）

- **AmmoniteBridge.scala**  
  作为 Ammonite REPL 的入口，提供了启动 REPL、动态执行代码以及通过 `withContext`、`runCode` 绑定变量的方法，便于在应用中执行动态或远程的 Scala 脚本。

### 4. 数据压缩（LZ4）

- **Lz4.scala**  
  基于 Apache Commons Compress 提供块级压缩与解压功能，接口包括：
  - `compress(data: Array[Byte])`: 对数据进行 LZ4 压缩。
  - `decompress(data: Array[Byte])`: 对数据进行 LZ4 解压。

### 5. 表达式语言（Els）

- **Els.scala**  
  定义了一套构造条件表达式的 DSL，包括：
  - 基础条件接口 `Cond[In]`（本质上为 `Function1[In, Boolean]`）。
  - 组合条件：`And` 与 `Or`，方便构造复合逻辑条件。
  - 具体比较条件：`Eq`、针对字符串的 `StartsWith`，以及针对数字的 `<` 与 `>` 条件。

### 6. 泛型与序列化

- **Serializable.scala**  
  扩展了 Java 的 `Serializable` trait，为旧库如 xgboost 等提供兼容支持。
- **Generic.scala（scala3fix 部分）**  
  定义了类型别名 `ValsIn[T]`，用于处理具有内部 `Values` 类型成员的泛型任务。

## 构建与依赖配置

- **构建工具**  
  使用 SBT 进行构建管理。根目录 `build.sbt` 定义 Scala 版本为 3.3.3，并配置了众多依赖（如 Ammonite、Scala3-staging、log4j、ZIO、ND4J 等），以保证项目在 Scala 3 环境下正常运行。

- **SBT 插件**  
  配置了依赖树查看、Scala3 迁移（`sbt-scala3-migrate`）、显式依赖检查等插件，帮助管理依赖冲突及版本兼容问题。

## 使用说明

### 编译与运行

- 编译项目：
  ```bash
  sbt compile
  ```
- 运行测试（项目中已配置 ScalaTest 等测试框架）：
  ```bash
  sbt test
  ```

### 模块获取示例

在系统初始化时（见 `di/init/SysConf.scala`）已注册了日志模块等：
```scala
def modules = Seq(
  ModuleDef.by[LogModule](new log.DebugConsoleModule),
  ModuleDef.by[TableModule](new TableModule)
)
```
在业务代码中可通过 DI 获取实例：
```scala
val logger = DI[LogModule]
// 使用 logger 进行日志记录，例如：logger.info("启动项目")
```

### 动态脚本执行

使用 Ammonite 集成提供的接口动态执行代码：
```scala
import ws.very.util.amm.Amm
val (result, watchables) = Amm.runCode("println(\"Hello, Ammonite!\")", Map.empty)
```

### 数据压缩示例

使用 LZ4 压缩及解压功能：
```scala
import ws.very.util.compress.Lz4

val data: Array[Byte] = "待压缩数据".getBytes("UTF-8")
val compressed = Lz4.block.compress(data)
val decompressed = Lz4.block.decompress(compressed)

println(new String(decompressed, "UTF-8"))
```

### 构建条件表达式

利用 Els 提供的 DSL 构造条件：
```scala
import ws.very.util.el.Els

val condition = Els.And(Seq(
  Els.Eq("test"),
  Els.Str.StartsWith("te")
))
println(condition("test"))  // 输出 true
```

## 环境变量配置

项目的 DI 模块会根据环境变量加载相应插件：
- `DiMode` 或 `DiMode-<接口名称>`：例如  
  ```bash
  export DiMode=prod
  export DiMode-LogModule=debug
  ```
  以便在不同环境中灵活切换模块实现。

## 总结

`very-util-lang` 提供了一套涵盖 DI、AOP、动态脚本、数据压缩、表达式构造以及会话管理的综合工具库，旨在简化常见编程任务，提高开发效率。项目结构清晰、模块功能明确，适合需要轻量级 DI、动态执行以及数据处理的应用场景，同时也为扩展和定制提供了良好的基础。

欢迎对本项目提出建议和改进，共同完善这一工具库!