fix: align thread-safety docs and add CI test coverage

.github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: Lint
+name: CI
 
 on:
   push:
@@ -7,6 +7,18 @@ on:
     branches: [ master, v2 ]
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Run tests
+        run: go test ./... -count=1 -race
+
   lint:
     runs-on: ubuntu-latest
 

README.md

@@ -115,6 +115,17 @@ err := dix.TryInject(di, func(svc *Service) {
 })
 ```
 
+### Thread Safety
+
+`Dix` containers are **not thread-safe**. Do not call `Provide` / `Inject` (or their `Try*` variants) concurrently on the same container instance.
+
+Recommended usage:
+
+- Register all providers during application startup (single goroutine).
+- After startup, only read resolved dependencies, or continue injection from a single goroutine.
+- Use separate `Dix` instances per goroutine if you need isolated containers.
+- For a process-wide singleton, prefer `dixglobal` only when startup is single-threaded.
+
 ### Startup Timeout / Slow Provider Warning
 
 Control long-running providers during startup:

README_zh.md

@@ -115,6 +115,17 @@ err := dix.TryInject(di, func(svc *Service) {
 })
 ```
 
+### 线程安全
+
+`Dix` 容器**不是线程安全的**。请勿在同一容器实例上并发调用 `Provide` / `Inject`（及其 `Try*` 变体）。
+
+推荐用法：
+
+- 在应用启动阶段（单 goroutine）完成全部 provider 注册。
+- 启动完成后仅读取已解析的依赖，或继续在单 goroutine 中注入。
+- 若需要隔离容器，请为每个 goroutine 使用独立的 `Dix` 实例。
+- 进程级单例请使用 `dixglobal`，且仅在启动阶段单线程注册。
+
 ### 启动超时 / 慢 Provider 告警
 
 可在启动阶段限制 provider 执行时间，并对慢调用输出告警：

Taskfile.yml

@@ -4,7 +4,7 @@ tasks:
   test:
     desc: Run tests with coverage
     cmds:
-      - go test -v ./dixinternal/... -covermode=count -coverprofile=coverage.out
+      - go test -v ./... -covermode=count -coverprofile=coverage.out
       - go tool cover -html=coverage.out -o coverage.html
 
   lint:

dix.go

@@ -78,3 +78,13 @@ func InjectTContext[T any](ctx context.Context, di *Dix, opts ...Option) T {
 }
 
 func Provide(di *Dix, data any) { di.Provide(data) }
+
+func TryProvide(di *Dix, data any) error { return di.TryProvide(data) }
+
+func TryInject(di *Dix, data any, opts ...Option) error {
+	return di.TryInject(data, opts...)
+}
+
+func TryInjectContext(ctx context.Context, di *Dix, data any, opts ...Option) error {
+	return di.TryInjectContext(ctx, data, opts...)
+}

dix_test.go

@@ -0,0 +1,49 @@
+package dix
+
+import (
+	"testing"
+)
+
+func TestVersion(t *testing.T) {
+	if Version() == "" {
+		t.Fatal("Version() returned empty string")
+	}
+}
+
+func TestTryProvide(t *testing.T) {
+	di := New()
+
+	type svc struct{ Name string }
+
+	if err := TryProvide(di, func() *svc { return &svc{Name: "ok"} }); err != nil {
+		t.Fatalf("TryProvide: %v", err)
+	}
+
+	if err := TryProvide(di, nil); err == nil {
+		t.Fatal("TryProvide(nil) should return error")
+	}
+}
+
+func TestTryInject(t *testing.T) {
+	di := New()
+
+	type dep struct{ V int }
+
+	if err := TryProvide(di, func() *dep { return &dep{V: 1} }); err != nil {
+		t.Fatalf("TryProvide: %v", err)
+	}
+
+	called := false
+	if err := TryInject(di, func(d *dep) { called = d.V == 1 }); err != nil {
+		t.Fatalf("TryInject: %v", err)
+	}
+	if !called {
+		t.Fatal("TryInject callback was not invoked correctly")
+	}
+
+	if err := TryInject(di, func(*missingType) {}); err == nil {
+		t.Fatal("TryInject with missing dependency should return error")
+	}
+}
+
+type missingType struct{}

dixinternal/dix.go

@@ -1026,8 +1026,8 @@ func (dix *Dix) injectStruct(ctx context.Context, structVal reflect.Value, opt O
 	return nil
 }
 
-// inject is the entry point for dependency injection
-// NOTE: This method is NOT thread-safe by itself. Use Inject() or TryInject() which handle locking.
+// inject is the internal entry point for dependency injection.
+// NOTE: The Dix container is not thread-safe; do not call Provide/Inject concurrently on the same container.
 func (dix *Dix) inject(ctx context.Context, param any, opts ...Option) (err error) {
 	paramType := "<nil>"
 	component := describeComponent(param)
@@ -1239,8 +1239,8 @@ func parseInputType(typ reflect.Type) []*providerInputType {
 	return input
 }
 
-// provide registers a constructor function
-// NOTE: This method is NOT thread-safe by itself. Use Provide() or TryProvide() which handle locking.
+// provide registers a constructor function.
+// NOTE: The Dix container is not thread-safe; do not call Provide/Inject concurrently on the same container.
 func (dix *Dix) provide(param any) {
 	component := describeComponent(param)
 	logDITrace("provide.start", "component", component)