Skip to content

Commit c41afe1

Browse files
authored
Merge pull request #27 from lvan100/main
Update comments
2 parents 347f6fa + 8b52401 commit c41afe1

File tree

9 files changed

+283
-5
lines changed

9 files changed

+283
-5
lines changed

conf/conf.go

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,108 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package conf provides a configuration binding framework with hierarchical resolution,
19+
type-safe mapping, and validation capabilities.
20+
21+
# Core Concepts:
22+
23+
The framework enables mapping configuration data from multiple sources into Go structures with:
24+
25+
- Hierarchical property resolution using ${key} syntax
26+
- Type-safe binding with automatic conversions
27+
- Expression-based validation
28+
- Extensible architecture via pluggable components
29+
30+
# Tag Syntax:
31+
32+
Struct tags use the following format:
33+
34+
value:"${key:=default}>>splitter"
35+
36+
Key features:
37+
- Nested keys (e.g., service.endpoint)
38+
- Dynamic defaults (e.g., ${DB_HOST:=localhost:${DB_PORT:=3306}})
39+
- Splitter chaining (e.g., >>json for JSON parsing)
40+
41+
# Data Binding:
42+
43+
Supports binding to various types with automatic conversion:
44+
45+
1. Primitives: Uses strconv for basic type conversions
46+
2. Complex Types:
47+
- Slices: From indexed properties or custom splitters
48+
- Maps: Via subkey expansion
49+
- Structs: Recursive binding of nested structures
50+
51+
3. Custom Types: Register converters using RegisterConverter
52+
53+
# Validation System:
54+
55+
1. Expression validation using expr tag:
56+
type Config struct {
57+
Port int `expr:"$ > 0 && $ < 65535"`
58+
}
59+
60+
2. Custom validators:
61+
RegisterValidateFunc("futureDate", func(t time.Time) bool {
62+
return t.After(time.Now())
63+
})
64+
65+
# File Support:
66+
67+
Built-in readers handle:
68+
- JSON (.json)
69+
- Properties (.properties)
70+
- YAML (.yaml/.yml)
71+
- TOML (.toml/.tml)
72+
73+
Register custom readers with RegisterReader.
74+
75+
# Property Resolution:
76+
77+
- Recursive ${} substitution
78+
- Type-aware defaults
79+
- Chained defaults (${A:=${B:=C}})
80+
81+
# Extension Points:
82+
83+
1. RegisterSplitter: Add custom string splitters
84+
2. RegisterConverter: Add type converters
85+
3. RegisterReader: Support new file formats
86+
4. RegisterValidateFunc: Add custom validators
87+
88+
# Examples:
89+
90+
Basic binding:
91+
92+
type ServerConfig struct {
93+
Host string `value:"${host:=localhost}"`
94+
Port int `value:"${port:=8080}"`
95+
}
96+
97+
Nested structure:
98+
99+
type AppConfig struct {
100+
DB Database `value:"${db}"`
101+
Timeout string `value:"${timeout:=5s}"`
102+
}
103+
104+
Slice binding:
105+
106+
type Config struct {
107+
Endpoints []string `value:"${endpoints}"` // Indexed properties
108+
Features []string `value:"${features}>>split"` // Custom splitter
109+
}
110+
111+
Validation:
112+
113+
type UserConfig struct {
114+
Age int `value:"${age}" expr:"$ >= 18"`
115+
Email string `value:"${email}" expr:"contains($, '@')"`
116+
Expires time.Time `value:"${expires}" expr:"futureDate($)"`
117+
}
118+
*/
17119
package conf
18120

19121
import (

gs/gstest/gstest.go

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,41 @@
1414
* limitations under the License.
1515
*/
1616

17-
// Package gstest is a unit testing framework designed for dependency injection in go-spring.
18-
// Unlike standard dependency injection, in unit testing mode, the framework gracefully ignores
19-
// non-critical dependency injection failures by logging warnings instead of halting execution.
20-
// This ensures seamless testing workflows when dealing with extensive dependencies,
21-
// as only the specific dependencies under test need to be validated, while others remain non-blocking.
17+
/*
18+
Package gstest provides unit testing utilities for dependency injection in Go-Spring framework.
19+
20+
Key Features:
21+
- Test environment configuration: jobs and servers are disabled, and the "test" profile is automatically activated
22+
- Autowire failure tolerance: non-critical autowiring errors are tolerated so that missing beans do not break tests
23+
- Type-safe mocking: compile-time checked MockFor/With methods for registering mock beans
24+
- Context lifecycle management: TestMain starts and stops the Go-Spring context automatically
25+
- Injection helpers: Get[T](t) and Wire(t, obj) simplify bean retrieval and dependency injection
26+
27+
Usage Pattern:
28+
29+
// Step 1: Register your mock beans before tests run
30+
// by calling `MockFor[T]().With(obj)` inside an `init()` function.
31+
func init() {
32+
gstest.MockFor[*Dao]().With(&MockDao{})
33+
}
34+
35+
// Step 2: Implement TestMain and invoke `gstest.TestMain(m, opts...)`
36+
// to bootstrap the application context, execute all tests, and then shut it down.
37+
// You can supply `BeforeRun` and `AfterRun` hooks to run code immediately before or after your test suite.
38+
func TestMain(m *testing.M) {
39+
gstest.TestMain(m)
40+
}
41+
42+
// Step 3: Write your test cases and use Get[T](t) or Wire(t, obj) to retrieve beans and inject dependencies.
43+
func TestService(t *testing.T) {
44+
// Retrieve autowired test target
45+
service := gstest.Get[*Service](t)
46+
47+
// Verify business logic
48+
result := service.Process()
49+
assert.Equal(t, expect, result)
50+
}
51+
*/
2252
package gstest
2353

2454
import (

gs/internal/gs_arg/arg.go

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,16 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package gs_arg provides implementation for function argument resolution and binding
19+
20+
Key Features:
21+
- Configuration property binding and dependency injection via struct tags
22+
- Precise positional binding through index-based arguments
23+
- Direct injection of fixed value arguments
24+
- Full support for variadic function parameters
25+
- Conditional execution with runtime evaluation
26+
*/
1727
package gs_arg
1828

1929
import (

gs/internal/gs_bean/bean.go

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,15 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package gs_bean provides core bean management for Go-Spring framework, featuring:
19+
20+
- Full lifecycle management (instantiation, DI, destruction)
21+
- Method-as-factory mechanism (generate child beans via configured rules)
22+
- Conditional registration (profile-based activation)
23+
- Type-safe interface export validation
24+
- Mock replacement mechanism
25+
*/
1726
package gs_bean
1827

1928
import (

gs/internal/gs_cond/cond.go

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,59 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package gs_cond provides conditional component registration for Go-Spring framework,
19+
offering runtime decision-making through various condition types.
20+
21+
1. Property Conditions
22+
23+
- Existence check:
24+
cond := OnProperty("db.host")
25+
26+
- Value matching:
27+
cond := OnProperty("env").HavingValue("prod")
28+
29+
- Expression evaluation:
30+
cond := OnProperty("port").HavingValue("expr:int($) > 1024")
31+
32+
- Missing handling:
33+
cond := OnProperty("debug").MatchIfMissing()
34+
35+
2. Bean Conditions
36+
37+
- Existence verification:
38+
cond := OnBean[Database]()
39+
40+
- Absence check:
41+
cond := OnMissingBean[Logger]()
42+
43+
- Singleton validation:
44+
cond := OnSingleBean[Config]()
45+
46+
3. Logical Combinators
47+
48+
- Conjunction:
49+
cond := And(condition1, condition2)
50+
51+
- Disjunction:
52+
cond := Or(condition1, condition2)
53+
54+
- Negation:
55+
cond := Not(condition)
56+
57+
- Universal negation:
58+
cond := None(condition1, condition2)
59+
60+
4. Custom Conditions
61+
62+
- Functional condition:
63+
cond := OnFunc(func(ctx gs.CondContext) (bool, error) {
64+
return time.Now().Hour() > 9, nil
65+
})
66+
67+
- Expression condition (Pending implementation):
68+
cond := OnExpression("beans('redis').size() > 0")
69+
*/
1770
package gs_cond
1871

1972
import (

gs/internal/gs_conf/conf.go

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,33 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package gs_conf provides hierarchical configuration management
19+
with multi-source support for Go-Spring framework.
20+
21+
Key Features:
22+
23+
1. Command-line argument parsing
24+
- Supports `-D key[=value]` format arguments
25+
- Customizable prefix via `GS_ARGS_PREFIX` environment variable
26+
- Example: `./app -D server.port=8080 -D debug`
27+
28+
2. Environment variable handling
29+
- Automatic loading of `GS_` prefixed variables
30+
- Conversion rules: `GS_DB_HOST=127.0.0.1` → `db.host=127.0.0.1`
31+
- Direct mapping of non-prefixed environment variables
32+
33+
3. Configuration file management
34+
- Supports properties/yaml/toml/json formats
35+
- Local configurations: ./conf/app.{properties|yaml|toml|json}
36+
- Remote configurations: ./conf/remote/app.{properties|yaml|toml|json}
37+
- Profile-based configurations (e.g., app-dev.properties)
38+
39+
4. Layered configuration hierarchy
40+
- Priority order: System config → File config → Env variables → CLI arguments
41+
- Provides AppConfig (application context) and BootConfig (boot context)
42+
- High-priority configurations override lower ones
43+
*/
1744
package gs_conf
1845

1946
import (

gs/internal/gs_conf/env.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ func (c *Environment) CopyTo(p *conf.MutableProperties) error {
4545
if len(ss) > 1 {
4646
v = ss[1]
4747
}
48+
if k == "" { // e.g., =::=::
49+
continue
50+
}
4851
var propKey string
4952
if strings.HasPrefix(k, prefix) {
5053
propKey = strings.TrimPrefix(k, prefix)

gs/internal/gs_dync/dync.go

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,50 @@
1414
* limitations under the License.
1515
*/
1616

17+
/*
18+
Package gs_dync provides dynamic configuration binding and refresh capabilities for Go applications.
19+
20+
This package is built on thread-safe atomic.Value storage with automatic type conversion and supports change listeners,
21+
making it suitable for components or services that need to react to configuration updates at runtime.
22+
23+
Key Features:
24+
- Type-safe and thread-safe encapsulation of configuration values
25+
- Change notification mechanism using channels
26+
- Hierarchical key resolution for nested structs and map keys
27+
- Fine-grained refresh logic that only updates affected objects
28+
- JSON serialization support for value persistence and transmission
29+
30+
Examples:
31+
32+
Basic value binding:
33+
34+
var v Value[int]
35+
_ = v.onRefresh(conf.Map(map[string]any{"key": 42}), conf.BindParam{Key: "key"})
36+
fmt.Print(v.Value()) // Output: 42
37+
38+
Binding nested structs:
39+
40+
type Config struct {
41+
Server struct {
42+
Port Value[int] `value:"${port}"`
43+
} `value:"${server}"`
44+
}
45+
46+
var cfg Config
47+
_ = p.RefreshField(reflect.ValueOf(&cfg), conf.BindParam{Key: "config"})
48+
49+
Change notification:
50+
51+
listener := v.NewListener()
52+
go func() {
53+
<-listener.C
54+
fmt.Print("value changed!")
55+
}()
56+
_ = v.onRefresh(conf.Map(map[string]any{"key": 100}), conf.BindParam{Key: "key"})
57+
58+
This package is ideal for use cases that require hot-reloading of configuration, have complex config structures,
59+
or demand reactive behavior to configuration changes.
60+
*/
1761
package gs_dync
1862

1963
import (

sdk/mcp/.keep

Whitespace-only changes.

0 commit comments

Comments
 (0)