improve documentation

lvan100 · lianghuan · commit d80e92e59445 · 2026-03-30T11:40:55.000+08:00
diff --git a/README.md b/README.md
@@ -2,7 +2,37 @@
 
 [English](README.md) | [中文](README_CN.md)
 
-`stdlib` is a collection of independent utility modules written in Go.
+`stdlib` is a collection of high-quality independent utility modules written in Go.
+It provides carefully crafted tools that complement the Go standard library,
+making everyday Go development more convenient and enjoyable.
+
+Each module is independent and can be used separately. Detailed documentation is available in each module's directory.
+
+## Available Modules
+
+| Module | Description |
+|--------|-------------|
+| [ctxcache](./ctxcache/) | Context-based caching utilities |
+| [errutil](./errutil/) | Error handling utilities, provides error wrapping, stack trace capture and more |
+| [fileutil](./fileutil/) | File system utilities |
+| [flatten](./flatten/) | Flatten nested data structures |
+| [formutil](./formutil/) | Form processing utilities |
+| [funcutil](./funcutil/) | Function utilities, lazy evaluation, partial application and more |
+| [goutil](./goutil/) | Generic Go language utilities, context cancellation control and more |
+| [hashutil](./hashutil/) | Hashing utilities |
+| [httpclt](./httpclt/) | HTTP client utilities |
+| [httpsvr](./httpsvr/) | HTTP server utilities |
+| [iterutil](./iterutil/) | Iterator and loop processing utilities |
+| [jsonflow](./jsonflow/) | JSON streaming processing toolkit |
+| [listutil](./listutil/) | List and linked list utilities |
+| [mathutil](./mathutil/) | Math and numeric utilities |
+| [md5util](./md5util/) | MD5 hashing convenience utilities |
+| [netutil](./netutil/) | Network related utilities |
+| [ordered](./ordered/) | Ordered map and set data structures |
+| [patchutil](./patchutil/) | Patch processing utilities |
+| [testing](./testing/) | Elegant fluent-style assertion library for unit testing, supports `assert` and `require` modes with type-specific assertions |
+| [textstyle](./textstyle/) | Text style and formatting utilities |
+| [typeutil](./typeutil/) | Type reflection and conversion utilities |
 
 ## License
 
diff --git a/README_CN.md b/README_CN.md
@@ -2,7 +2,35 @@
 
 [English](README.md) | [中文](README_CN.md)
 
-`stdlib` 是一个包含多个独立 Go 语言工具模块的集合库。
+`stdlib` 是一系列精心设计的独立 Go 语言工具模块集合，对 Go 标准库进行了有益补充，让日常 Go 开发更加便捷愉悦。
+
+每个模块都是独立的，可以单独使用。每个模块目录下都有详细的文档说明。
+
+## 可用模块
+
+| 模块 | 说明 |
+|--------|-------------|
+| [ctxcache](./ctxcache/) | 基于 Context 的缓存工具 |
+| [errutil](./errutil/) | 错误处理工具，提供错误包装、栈追踪捕获等功能 |
+| [fileutil](./fileutil/) | 文件系统工具 |
+| [flatten](./flatten/) | 嵌套数据结构扁平化 |
+| [formutil](./formutil/) | 表单处理工具 |
+| [funcutil](./funcutil/) | 函数工具，延迟求值、偏函数应用等 |
+| [goutil](./goutil/) | Go 通用工具，上下文取消控制等功能 |
+| [hashutil](./hashutil/) | 哈希计算工具 |
+| [httpclt](./httpclt/) | HTTP 客户端工具 |
+| [httpsvr](./httpsvr/) | HTTP 服务端工具 |
+| [iterutil](./iterutil/) | 迭代器和循环处理工具 |
+| [jsonflow](./jsonflow/) | JSON 流式处理工具包 |
+| [listutil](./listutil/) | 列表和链表工具 |
+| [mathutil](./mathutil/) | 数学数值工具 |
+| [md5util](./md5util/) | MD5 哈希便捷工具 |
+| [netutil](./netutil/) | 网络相关工具 |
+| [ordered](./ordered/) | 有序 Map 和有序 Set 数据结构 |
+| [patchutil](./patchutil/) | 补丁处理工具 |
+| [testing](./testing/) | 优雅的流式 API 风格单元测试断言库，支持 `assert` 和 `require` 两种模式，提供丰富的类型专属断言 |
+| [textstyle](./textstyle/) | 文本样式格式化工具 |
+| [typeutil](./typeutil/) | 类型反射和转换工具 |
 
 ## 许可证
 
diff --git a/ctxcache/README.md b/ctxcache/README.md
@@ -38,7 +38,7 @@ Use the `Set` function to assign a value to a key:
 ```go
 err := ctxcache.Set(ctx, "user", userInfo)
 if err != nil {
-// handle error
+    // handle error
 }
 ```
 
@@ -51,7 +51,7 @@ Use the `Get` function to retrieve a value:
 ```go
 value, err := ctxcache.Get[UserType](ctx, "user")
 if err != nil {
-// handle error
+    // handle error
 }
 ```
 
diff --git a/ctxcache/README_CN.md b/ctxcache/README_CN.md
@@ -36,7 +36,7 @@ defer cancel() // 在请求边界处清理缓存
 ```go
 err := ctxcache.Set(ctx, "user", userInfo)
 if err != nil {
-// 处理错误
+    // 处理错误
 }
 ```
 
@@ -49,7 +49,7 @@ if err != nil {
 ```go
 value, err := ctxcache.Get[UserType](ctx, "user")
 if err != nil {
-// 处理错误
+    // 处理错误
 }
 ```
 
diff --git a/testing/README.md b/testing/README.md
@@ -1,51 +1,260 @@
-# Assert & Require
+# testing
 
 [English](README.md) | [中文](README_CN.md)
 
-Go-Spring Testing provides two packages for making assertions in tests: `assert` and `require`. Both packages offer a
-fluent API for writing clear and expressive test assertions.
+Go-Spring Testing is an elegant test assertion library designed for Go, providing a Fluent API style that
+makes your test code clearer and more readable.
 
-### assert
+## Features Overview
 
-The `assert` package provides assertion functions that allow tests to continue running even when an assertion fails.
+- 📝 **Dual-mode support**: Provides both `assert` and `require` modes to meet different scenario requirements
+- 💧 **Fluent API**: Method chaining makes code more readable, close to natural language
+- 🏷️ **Type safety**: Generics guarantee type safety with compile-time error checking
+- 🔧 **Type-specific**: Provides dedicated assertion methods for different data types
+- 🧩 **Feature-rich**: Covers the vast majority of assertion needs in daily testing, supporting generic values,
+  errors, numbers, strings, slices, maps, panic detection, and more
+- ✅ **Zero dependencies**: Only depends on the Go standard library
 
-When an assertion in the `assert` package fails, the test function continues executing subsequent assertions. This is
-useful when you want to report multiple failures in a single test run.
+## assert vs require
 
-### require
+Go-Spring Testing provides two packages to meet different testing needs:
 
-The `require` package provides assertion functions that stop test execution immediately when an assertion fails.
+### `assert` package
 
-When an assertion in the `require` package fails, the test function stops executing and no further assertions are
-checked. This is useful when subsequent assertions would panic or cause other issues if a critical condition is not met.
+The `assert` package provides assertion functions that **do not terminate test execution when an assertion fails**.
 
-### Basic Example
+When an assertion fails, the test continues running and subsequent assertions will still be checked.
+This is very useful when you want to report multiple failures in a single test run and see all issues at once.
+
+### `require` package
+
+The `require` package provides assertion functions that **immediately stop test execution when an assertion fails**.
+
+When an assertion fails, the test terminates immediately and no further assertions are checked.
+This is suitable for scenarios where critical conditions are not met and subsequent assertions may cause panics or other issues.
+For example, when you need to verify that an object is non-nil before you can proceed with subsequent operations.
+
+## Basic Example
 
 ```go
 package main
 
 import (
 	"testing"
+	"os"
+	"math"
 
 	"github.com/go-spring/stdlib/testing/assert"
 	"github.com/go-spring/stdlib/testing/require"
 )
 
-func TestSomething(t *testing.T) {
-	// Using assert - test continues on failure
-	assert.That(t, "hello").Equal("hello")
-	assert.Number(t, 42).GreaterThan(40)
+func TestExample(t *testing.T) {
+	// Generic assertions - works with any type
+	assert.That(t, "hello").Equal("hello")        // Equality assertion
+	assert.That(t, user).NotNil()                 // Non-nil assertion
+	assert.That(t, 42).True()                     // Boolean is true
+
+	// Using require - test stops immediately on failure
+	require.That(t, user).NotNil()
+
+	// Error assertions
+	err := someFunc()
+	assert.Error(t, err).NotNil()                 // Expect an error to occur
+	assert.Error(t, err).Is(os.IsNotExist)         // Check error type using errors.Is
+
+	// Number assertions
+	assert.Number(t, 42).GreaterThan(40)          // Greater than
+	assert.Number(t, 100).Between(0, 200)          // Within range
+	assert.Number(t, 0).Zero()                     // Equal to zero
+	assert.Number(t, 3.14).InDelta(math.Pi, 0.01)  // Floating point comparison with tolerance
+
+	// String assertions
+	assert.String(t, "user@example.com").IsEmail()      // Validate email format
+	assert.String(t, "hello world").Contains("world")   // Contains substring
+	assert.String(t, "hello").HasPrefix("he")            // Prefix check
+	assert.String(t, `{"name": "bob"}`).JSONEqual(`{"name":"bob"}`) // JSON structural equality
+
+	// Slice assertions
+	assert.Slice(t, []int{1, 2, 3}).Contains(2)         // Contains element
+	assert.Slice(t, []int{1, 2, 3}).Length(3)           // Length check
+	assert.Slice(t, []int{1, 2, 3}).NotEmpty()           // Not empty check
+	assert.Slice(t, []int{1, 2, 3}).AllUnique()         // All elements unique
 
-	// Using require - test stops on failure
-	require.That(t, someValue).NotNil()
+	// Map assertions
+	m := map[string]int{"a": 1, "b": 2}
+	assert.Map(t, m).ContainsKey("a")                    // Contains key
+	assert.Map(t, m).ContainsKeyValue("a", 1)           // Contains key-value pair
+	assert.Map(t, m).Length(2)                           // Length check
 
-	// Type-specific assertions
-	assert.String(t, "user@example.com").IsEmail()
-	assert.Number(t, 100).Between(0, 200)
-	assert.Slice(t, []int{1, 2, 3}).Contains(2)
+	// Panic assertion
+	assert.Panic(t, func() {
+		panic("something wrong happened")
+	}, "wrong")  // Assert that panic occurs and message contains "wrong"
 }
 ```
 
+## Assertion Method Reference
+
+### Generic Assertions (That)
+
+These generic assertion methods can be used with any type.
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `True(...msg)` | Verify that the boolean value is `true` |
+| `False(...msg)` | Verify that the boolean value is `false` |
+| `Nil(...msg)` | Verify that the value is `nil` (correctly handles nil in interface types) |
+| `NotNil(...msg)` | Verify that the value is not `nil` |
+| `Equal(expected, ...msg)` | Deep comparison using `reflect.DeepEqual` |
+| `NotEqual(expected, ...msg)` | Verify not deeply equal |
+| `Same(expected, ...msg)` | Exact comparison using `==` (same pointer address) |
+| `NotSame(expected, ...msg)` | Comparison using `!=` |
+| `TypeOf(interface, ...msg)` | Verify that the type is assignable to the target type |
+| `Implements(interface, ...msg)` | Verify that the type implements the specified interface |
+| `Has(expected, ...msg)` | Call the value's `Has` method, verify it returns `true` |
+| `Contains(expected, ...msg)` | Call the value's `Contains` method, verify it returns `true` |
+
+### Error Assertions (Error)
+
+Dedicated assertions for `error` type.
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Nil(...msg)` | Verify the error is `nil` |
+| `NotNil(...msg)` | Verify the error is not `nil` |
+| `Is(target, ...msg)` | Verify error is the target error using `errors.Is` |
+| `NotIs(target, ...msg)` | Verify error is not the target error using `errors.Is` |
+| `String(expect, ...msg)` | Verify error message string equality |
+| `Matches(pattern, ...msg)` | Verify error message matches regular expression |
+
+### Number Assertions (Number)
+
+Supports all numeric types (`int`/`uint`/`float`, etc.).
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Equal(expect, ...msg)` | Equal to |
+| `NotEqual(expect, ...msg)` | Not equal to |
+| `GreaterThan(expect, ...msg)` | Greater than |
+| `GreaterOrEqual(expect, ...msg)` | Greater than or equal to |
+| `LessThan(expect, ...msg)` | Less than |
+| `LessOrEqual(expect, ...msg)` | Less than or equal to |
+| `Zero(...msg)` | Equal to zero |
+| `NotZero(...msg)` | Not equal to zero |
+| `Positive(...msg)` | Positive number |
+| `NotPositive(...msg)` | Non-positive (≤ 0) |
+| `Negative(...msg)` | Negative number |
+| `NotNegative(...msg)` | Non-negative (≥ 0) |
+| `Between(lower, upper, ...msg)` | Within the interval (inclusive) |
+| `NotBetween(lower, upper, ...msg)` | Not within the interval |
+| `InDelta(expect, delta, ...msg)` | Within the expected error tolerance |
+| `IsNaN(...msg)` | Is NaN (only valid for floats) |
+| `IsInf(sign, ...msg)` | Is infinity (sign ≥ 0 for +Inf, < 0 for -Inf) |
+| `IsFinite(...msg)` | Is a finite number (not NaN and not Inf) |
+
+### String Assertions (String)
+
+Dedicated assertions for `string` type.
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Length(length, ...msg)` | Verify length |
+| `Blank(...msg)` | Verify empty or all whitespace |
+| `NotBlank(...msg)` | Verify not blank |
+| `Equal(expect, ...msg)` | Equal to |
+| `NotEqual(expect, ...msg)` | Not equal to |
+| `EqualFold(expect, ...msg)` | Case-insensitive equality |
+| `JSONEqual(expect, ...msg)` | Deserialize JSON and compare structural equality |
+| `Matches(pattern, ...msg)` | Match regular expression |
+| `HasPrefix(prefix, ...msg)` | Starts with the specified prefix |
+| `HasSuffix(suffix, ...msg)` | Ends with the specified suffix |
+| `Contains(substr, ...msg)` | Contains substring |
+| `IsLowerCase(...msg)` | All lowercase |
+| `IsUpperCase(...msg)` | All uppercase |
+| `IsNumeric(...msg)` | All digits |
+| `IsAlpha(...msg)` | All letters |
+| `IsAlphaNumeric(...msg)` | All letters and digits |
+| `IsEmail(...msg)` | Verify is a valid email address |
+| `IsURL(...msg)` | Verify is a valid URL |
+| `IsIPv4(...msg)` | Verify is a valid IPv4 address |
+| `IsHex(...msg)` | Verify is a valid hexadecimal string |
+| `IsBase64(...msg)` | Verify is a valid Base64 encoding |
+
+### Slice Assertions (Slice)
+
+Dedicated assertions for slice type `[]T`.
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Length(length, ...msg)` | Verify length |
+| `Nil(...msg)` | Verify is nil |
+| `NotNil(...msg)` | Verify is not nil |
+| `Empty(...msg)` | Verify empty (length is zero) |
+| `NotEmpty(...msg)` | Verify not empty |
+| `Equal(expect, ...msg)` | Slice is exactly equal (element order and values match) |
+| `NotEqual(expect, ...msg)` | Verify not equal |
+| `Contains(element, ...msg)` | Contains element |
+| `NotContains(element, ...msg)` | Does not contain element |
+| `ContainsSlice(sub, ...msg)` | Contains consecutive sub-slice |
+| `NotContainsSlice(sub, ...msg)` | Does not contain consecutive sub-slice |
+| `HasPrefix(prefix, ...msg)` | Starts with the specified slice as a prefix |
+| `HasSuffix(suffix, ...msg)` | Ends with the specified slice as a suffix |
+| `AllUnique(...msg)` | All elements are unique |
+| `AllMatches(fn, ...msg)` | All elements satisfy the predicate function |
+| `AnyMatches(fn, ...msg)` | At least one element satisfies the predicate function |
+| `NoneMatches(fn, ...msg)` | No element satisfies the predicate function |
+
+### Map Assertions (Map)
+
+Dedicated assertions for map type `map[K]V`.
+**All methods support adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Length(length, ...msg)` | Verify length |
+| `Nil(...msg)` | Verify is nil |
+| `NotNil(...msg)` | Verify is not nil |
+| `Empty(...msg)` | Verify empty |
+| `NotEmpty(...msg)` | Verify not empty |
+| `Equal(expect, ...msg)` | Exactly equal |
+| `NotEqual(expect, ...msg)` | Not equal |
+| `ContainsKey(key, ...msg)` | Contains key |
+| `NotContainsKey(key, ...msg)` | Does not contain key |
+| `ContainsValue(value, ...msg)` | Contains value |
+| `NotContainsValue(value, ...msg)` | Does not contain value |
+| `ContainsKeyValue(key, value, ...msg)` | Contains the specified key-value pair |
+| `ContainsKeys(keys, ...msg)` | Contains all specified keys |
+| `NotContainsKeys(keys, ...msg)` | Does not contain any of the specified keys |
+| `ContainsValues(values, ...msg)` | Contains all specified values |
+| `NotContainsValues(values, ...msg)` | Does not contain any of the specified values |
+| `SubsetOf(expect, ...msg)` | Current map is a subset of expect (all key-value pairs exist in expect) |
+| `SupersetOf(expect, ...msg)` | Current map is a superset of expect (all key-value pairs in expect exist in current) |
+| `HasSameKeys(expect, ...msg)` | Has exactly the same set of keys as expect |
+| `HasSameValues(expect, ...msg)` | Has exactly the same multiset of values as expect (order doesn't matter) |
+
+### Panic Assertion
+
+Used to detect whether a function will panic. This is a top-level function.
+**Supports adding `msg ...string` at the end for custom error messages**.
+
+| Method | Description |
+|--------|-------------|
+| `Panic(t, fn, pattern, ...msg)` | Assert that `fn` panics, and the panic message matches the regex `pattern` |
+
+## Custom Error Messages
+
+All assertion methods support adding custom error messages at the end:
+
+```go
+assert.That(t, result).Equal(expected, "result should match expected")
+assert.Number(t, age).GreaterThan(18, "user should be an adult")
+```
+
 ## License
 
 Apache License 2.0
diff --git a/testing/README_CN.md b/testing/README_CN.md
