feat: align JS exports to PascalCase (by AI)

refactor: align with starter v1.5.3 Start/Wait pattern
refactor(service): export WebServer and NewWebServer for compatibility
2026-06-10 12:14:54 +08:00 · 2026-06-08 00:20:13 +08:00 · 2026-06-06 09:35:02 +08:00 · 2026-06-06 08:59:14 +08:00 · 2026-06-05 21:15:04 +08:00
15 changed files with 227 additions and 71 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,5 +1,21 @@
 # CHANGELOG - go/service

+## v1.5.12 (2026-06-07)
+- **基础设施对齐: 切换至 starter v1.5.3 编排模式**:
+  - 弃用已废弃的 `starter.Run()`，全面转向 `starter.Start() / starter.Wait()`。
+
+## v1.5.11 (2026-06-06)
+- **修复: 路由与静态文件匹配鲁棒性增强**:
+  - **路径参数提取**: 修复了正则匹配路由（如 `{name}`）无法正确提取并注入路径参数到业务函数的问题。
+  - **静态文件匹配**: 引入 `hostStatics` 有序路由表，实现“最长前缀匹配”策略，解决在复杂或重叠的静态目录配置下的匹配歧义问题。
+  - **URL 兼容性**: 针对包含空格、中文字符及特殊符号的复杂 URL，在路由与静态文件匹配阶段统一进行 Robust 处理，彻底解决 404 隐患。
+  - **Host 匹配增强**: 验证并明确了 Host 匹配的灵活性，支持 `hostname:port`, `hostname`, `:port` 的自动降级匹配。
+
+## v1.5.10 (2026-06-05)
+- **修复: Static 服务 URL 解码**:
+  - 修复了 \`service.Static()\` 在处理包含空格或特殊字符（如 \`%20\`）的请求路径时，因未解码导致文件匹配失败的问题。
+  - 在路由匹配阶段提前进行 URL Path 解码，提升整体路径匹配的健壮性。
+
 ## v1.5.9 (2026-06-05)
 - **优化: 低代码环境深度对齐**:
  - **JS 友好型 Header**: 引入 \`service.Header\` 包装类，提供大小写不敏感的 \`Get/Set/Add/Del\` 方法，提升脚本开发体验。
--- a/document.go
+++ b/document.go
@ -24,7 +24,7 @@ func MakeDocument() []Api {
 	return DefaultServer.MakeDocument()
 }

-func (ws *webServer) MakeDocument() []Api {
+func (ws *WebServer) MakeDocument() []Api {
 	out := make([]Api, 0)

 	// 1. Rewrite & Proxy
--- a/go.mod
+++ b/go.mod
@ -13,7 +13,7 @@ require (
 	apigo.cc/go/log v1.5.5
 	apigo.cc/go/redis v1.5.0
 	apigo.cc/go/safe v1.5.0
-	apigo.cc/go/starter v1.5.2
+	apigo.cc/go/starter v1.5.3
 	apigo.cc/go/timer v1.5.0
 	github.com/gorilla/websocket v1.5.3
 	golang.org/x/net v0.54.0
--- a/go.sum
+++ b/go.sum
@ -16,8 +16,7 @@ apigo.cc/go/id v1.5.0 h1:MjNWPhBhDsoXaLeJDv/0wfJmVMU9EvOs8pWYfsTQ6e8=
 apigo.cc/go/id v1.5.0/go.mod h1:qhu4a1/KLc/XcBpcsRu+mXZt7U7Wvd9zMcPs4VspuPA=
 apigo.cc/go/jsmod v1.5.0 h1:JgQtJNiJWy1NOP9AzE8NX5VXJkpO/x3GqLsCCSny5Ec=
 apigo.cc/go/jsmod v1.5.0/go.mod h1:bmyeZtOAP/j5am+YRnaiM89smysK24K7ebk0koFtsSw=
-apigo.cc/go/log v1.5.4 h1:LNyU4v09gfcnZOY53ctnXoKzo45FHoEcPR33lk6PBaY=
-apigo.cc/go/log v1.5.4/go.mod h1:Djy+I5aLhGB/EjwRz4KHqkVEz584IAD55FAFiIfInuo=
+apigo.cc/go/log v1.5.5 h1:AFU7d7AQxkpgDHl7SnlEwd6yzGSFAlnrrjbrNDQnQHI=
 apigo.cc/go/rand v1.5.0 h1:1o8hh8fhdBuk1/h02IvugvamuT3dkWbVJrqEJVQKB2E=
 apigo.cc/go/rand v1.5.0/go.mod h1:Lh98S2dm9UY0X+M+kNQQEKyXHG5pcCKSFPyXN0QCGdk=
 apigo.cc/go/redis v1.5.0 h1:VXNDqzKj87BchF7ubDEH+T6lp8NrjeK0izU4ooo7u1A=
@ -26,8 +25,7 @@ apigo.cc/go/safe v1.5.0 h1:W1NblmcU8cex1f9Y5z8mNLUJOzZTE1s6fszb3FbhGnk=
 apigo.cc/go/safe v1.5.0/go.mod h1:OfQ5d6COePSGEuPvMeOk6KagX2sezw7nvKh7exj9SeM=
 apigo.cc/go/shell v1.5.0 h1:WLDMMqUU0INeaBDmQsTPr0h/NfB2RknAtiJ5NL467+Q=
 apigo.cc/go/shell v1.5.0/go.mod h1:rYHA77d5hEsQHcJrbAWf1pHy0sxayeJ0gU55LA/JWQk=
-apigo.cc/go/starter v1.5.2 h1:bSNByK9uU+4+Rw8a83TNhQnUUjCPfJj7DVUpEuCD2wg=
-apigo.cc/go/starter v1.5.2/go.mod h1:iu3AnpqpriJBiTJC0MJyeFxGmmFto+SU+S2d96XhRco=
+apigo.cc/go/starter v1.5.3 h1:kakDapul+l63w3Ah1pnBxD1mup9Fbt821omWCiaGwCE=
 apigo.cc/go/timer v1.5.0 h1:iPo/IQn+iuhBRI1/MR1txwZnamef/RBBfOiIlBiqkgk=
 apigo.cc/go/timer v1.5.0/go.mod h1:kOnqTTX+zA4AH7SfC+LpUm4ZvS+DVyWWMqul/V5QWJs=
 github.com/gomodule/redigo v2.0.0+incompatible h1:K/R+8tc58AaqLkqG2Ol3Qk+DR/TlNuhuh457pBFPtt0=
--- a/handler.go
+++ b/handler.go
@ -7,6 +7,7 @@ import (
 	"apigo.cc/go/timer"
 	"io"
 	"net/http"
+	"net/url"
 	"reflect"
 	"runtime/debug"
 	"strings"
@ -15,7 +16,7 @@ import (
 )

 type RouteHandler struct {
-	ws               *webServer
+	ws               *WebServer
 	webRequestingNum int64
 }

@ -148,7 +149,7 @@ func (rh *RouteHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	}

 	// 3. 路由匹配
-	path := r.URL.Path
+	path, _ := url.PathUnescape(r.URL.Path)
 	host := r.Host

 	// 处理静态文件
@ -156,7 +157,7 @@ func (rh *RouteHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		goto filter
 	}

-	s, wsc = ws.findService(r.Method, host, path)
+	s, wsc = ws.findService(r.Method, host, path, args)

 	// 4. 参数解析 (Form & Body)
 	parseRequestArgs(request, args)
@ -244,7 +245,7 @@ func hostOnly(host string) string {
 	return h
 }

-func (ws *webServer) findService(method, host, path string) (*webServiceType, *websocketServiceType) {
+func (ws *WebServer) findService(method, host, path string, args map[string]any) (*webServiceType, *websocketServiceType) {
 	ws.webServicesLock.RLock()
 	defer ws.webServicesLock.RUnlock()

@ -288,6 +289,14 @@ func (ws *webServer) findService(method, host, path string) (*webServiceType, *w
 					continue
 				}
 				if s.pathMatcher != nil && s.pathMatcher.MatchString(path) {
+					matches := s.pathMatcher.FindStringSubmatch(path)
+					if len(matches) > 1 {
+						for i, name := range s.pathArgs {
+							if i+1 < len(matches) {
+								args[name] = matches[i+1]
+							}
+						}
+					}
 					return s, nil
 				}
 			}
@ -330,7 +339,7 @@ func parseRequestArgs(request *Request, args map[string]any) {
 	}
 }

-func (ws *webServer) checkAuth(authLevel int, options *WebServiceOptions, request *Request, response *Response, args map[string]any, logger *log.Logger) (bool, any) {
+func (ws *WebServer) checkAuth(authLevel int, options *WebServiceOptions, request *Request, response *Response, args map[string]any, logger *log.Logger) (bool, any) {
 	ac := ws.webAuthCheckers[authLevel]
 	if ac == nil {
 		ac = ws.webAuthChecker
@ -349,7 +358,7 @@ func (ws *webServer) checkAuth(authLevel int, options *WebServiceOptions, reques
 	return pass, obj
 }

-func (ws *webServer) doWebService(service *webServiceType, request *Request, response *Response, args map[string]any,
+func (ws *WebServer) doWebService(service *webServiceType, request *Request, response *Response, args map[string]any,
 	result any, logger *log.Logger, object any) any {
 	if result != nil {
 		return result
@ -427,7 +436,7 @@ func outputResult(response *Response, result any) {
 		_, _ = response.Write(data)
 	}
 }
-func (ws *webServer) handleClientKeys(request *Request, response *Response) {
+func (ws *WebServer) handleClientKeys(request *Request, response *Response) {
 	// SessionId
 	if ws.usedSessionIdKey != "" {
 		sessionId := request.Header().Get(ws.usedSessionIdKey)
--- a/js_export.go
+++ b/js_export.go
@ -14,7 +14,7 @@ func init() {
 		"__exportFile":      func() *jsUploadFile { return &jsUploadFile{} },

 		// 功能函数
-		"upgrade": Upgrade,
+		"Upgrade": Upgrade,
 	})
 }

--- a/proxy.go
+++ b/proxy.go
@ -88,7 +88,7 @@ func (hc *HostContext) Proxy(authLevel int, path string, to string) *HostContext
 	return hc
 }

-func (ws *webServer) findProxy(request *Request) (int, *string, *string, string) {
+func (ws *WebServer) findProxy(request *Request) (int, *string, *string, string) {
 	host := request.Host
 	hostOnly, port, _ := strings.Cut(host, ":")
 	hosts := []string{host}
@ -145,7 +145,7 @@ func (ws *webServer) findProxy(request *Request) (int, *string, *string, string)
 	return 0, nil, nil, ""
 }

-func (ws *webServer) processProxy(request *Request, response *Response, logger *log.Logger) bool {
+func (ws *WebServer) processProxy(request *Request, response *Response, logger *log.Logger) bool {
 	authLevel, proxyToApp, proxyToPath, foundHost := ws.findProxy(request)

 	if proxyToApp == nil || proxyToPath == nil || *proxyToApp == "" || *proxyToPath == "" {
@ -186,7 +186,7 @@ func (ws *webServer) processProxy(request *Request, response *Response, logger *
 	return true
 }

-func (ws *webServer) getHttpClient() *gohttp.Client {
+func (ws *WebServer) getHttpClient() *gohttp.Client {
 	// 尝试从注入对象获取
 	if obj := ws.GetInject(reflect.TypeOf(&gohttp.Client{})); obj != nil {
 		return obj.(*gohttp.Client)
@ -198,7 +198,7 @@ func (ws *webServer) getHttpClient() *gohttp.Client {
 	return gohttp.NewClient(timeout)
 }

-func (ws *webServer) checkAuthForProxy(authLevel int, request *Request, response *Response, logger *log.Logger) (bool, any) {
+func (ws *WebServer) checkAuthForProxy(authLevel int, request *Request, response *Response, logger *log.Logger) (bool, any) {
 	ac := ws.webAuthCheckers[authLevel]
 	if ac == nil {
 		ac = ws.webAuthChecker
@ -245,7 +245,7 @@ func ReplaceProxies(host string, rules []ProxyRule) {
 	DefaultServer.ReplaceProxies(host, rules)
 }

-func (ws *webServer) ReplaceProxies(host string, rules []ProxyRule) {
+func (ws *WebServer) ReplaceProxies(host string, rules []ProxyRule) {
 	newProxies := make([]*proxyType, 0, len(rules))
 	for _, r := range rules {
 		newProxies = append(newProxies, parseProxyRule(r.AuthLevel, r.Path, r.ToApp, r.ToPath, r.To))
--- a/reload.go
+++ b/reload.go
@ -17,14 +17,14 @@ func OnReload(handler func() error) {
 	DefaultServer.OnReload(handler)
 }

-func (ws *webServer) OnReload(handler func() error) {
+func (ws *WebServer) OnReload(handler func() error) {
 	globalReloadHook.lock.Lock()
 	defer globalReloadHook.lock.Unlock()
 	globalReloadHook.hooks = append(globalReloadHook.hooks, handler)
 }

 // triggerReload 触发所有注册的重新加载钩子
-func (ws *webServer) triggerReload() error {
+func (ws *WebServer) triggerReload() error {
 	globalReloadHook.lock.RLock()
 	hooks := make([]func() error, len(globalReloadHook.hooks))
 	copy(hooks, globalReloadHook.hooks)
--- a/response.go
+++ b/response.go
@ -19,7 +19,7 @@ type Response struct {
 	dontLog200    bool                `js:"-"`
 	dontLogArgs   []string            `js:"-"`
 	ProxyHeader   *http.Header        `js:"-"`
-	server        *webServer          `js:"-"`
+	server        *WebServer          `js:"-"`
 }

 func (r *Response) SetCookie(cookie *Cookie) {
@ -38,7 +38,7 @@ func (r *Response) SetCookie(cookie *Cookie) {
 }

 // NewResponse 创建 Response 包装
-func NewResponse(writer http.ResponseWriter, server *webServer) *Response {
+func NewResponse(writer http.ResponseWriter, server *WebServer) *Response {
 	return &Response{
 		Writer: writer,
 		Code:   http.StatusOK,
--- a/rewrite.go
+++ b/rewrite.go
@ -49,7 +49,7 @@ func (hc *HostContext) Rewrite(path string, to string) *HostContext {
 	return hc
 }

-func (ws *webServer) processRewrite(request *Request, response *Response, logger *log.Logger) bool {
+func (ws *WebServer) processRewrite(request *Request, response *Response, logger *log.Logger) bool {
 	host := request.Host
 	hostOnly, port, _ := strings.Cut(host, ":")
 	hosts := []string{host}
@ -139,7 +139,7 @@ func ReplaceRewrites(host string, rules []RewriteRule) {
 	DefaultServer.ReplaceRewrites(host, rules)
 }

-func (ws *webServer) ReplaceRewrites(host string, rules []RewriteRule) {
+func (ws *WebServer) ReplaceRewrites(host string, rules []RewriteRule) {
 	newRewrites := make([]*rewriteType, 0, len(rules))
 	for _, r := range rules {
 		newRewrites = append(newRewrites, parseRewriteRule(r.Path, r.ToPath, r.To))
--- a/robustness_test.go
+++ b/robustness_test.go
@ -0,0 +1,114 @@
+package service
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"net/url"
+)
+
+func TestStaticRobustness(t *testing.T) {
+	tempDir, _ := os.MkdirTemp("", "robustness_test")
+	defer os.RemoveAll(tempDir)
+
+	// 创建复杂的目录结构
+	subDir := filepath.Join(tempDir, "The NPC Awakens", "The Loop", "scene", "M")
+	_ = os.MkdirAll(subDir, 0755)
+
+	fileName := "画面逐渐亮起，铁匠铺的铁锤在无人操作的情况下，机械地敲击着烧红的铁块。_large.webp"
+	testFile := filepath.Join(subDir, fileName)
+	content := []byte("fake webp content")
+	_ = os.WriteFile(testFile, content, 0644)
+
+	// 注册静态目录
+	ws := NewWebServer()
+	ws.Config.App = "test"
+	ws.Static("/img/", tempDir)
+
+	rh := &RouteHandler{ws: ws}
+
+	// 构造编码后的请求路径
+	encodedPath := "/img/" + url.PathEscape("The NPC Awakens/The Loop/scene/M/画面逐渐亮起，铁匠铺的铁锤在无人操作的情况下，机械地敲击着烧红的铁块。_large.webp")
+	
+	// 测试静态文件访问
+	req := httptest.NewRequest("GET", encodedPath+"?v=1780317467305", nil)
+	w := httptest.NewRecorder()
+	rh.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("Expected 200 for complex static file, got %d. Path: %s", w.Code, encodedPath)
+	} else if string(w.Body.Bytes()) != string(content) {
+		t.Errorf("Content mismatch for complex static file")
+	}
+}
+
+func TestDynamicRobustness(t *testing.T) {
+	ws := NewWebServer()
+	ws.Config.App = "test"
+	
+	pathPattern := "/api/scene/{name}"
+	ws.Host("*").GET(pathPattern, func(in struct{ Name string }) string {
+		return "Hello " + in.Name
+	})
+
+	rh := &RouteHandler{ws: ws}
+
+	complexName := "画面逐渐亮起，铁匠铺的铁锤"
+	encodedPath := "/api/scene/" + url.PathEscape(complexName)
+
+	req := httptest.NewRequest("GET", encodedPath, nil)
+	w := httptest.NewRecorder()
+	rh.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("Expected 200 for complex dynamic path, got %d", w.Code)
+	}
+	expectedBody := "Hello " + complexName
+	if w.Body.String() != expectedBody {
+		t.Errorf("Got body: %s, expected: %s", w.Body.String(), expectedBody)
+	}
+}
+
+func TestHostMatching(t *testing.T) {
+	ws := NewWebServer()
+	ws.Config.App = "test"
+
+	// 1. 注册只带端口的 Host
+	ws.Host(":8080").GET("/port", func() string { return "port" })
+	// 2. 注册只带域名的 Host
+	ws.Host("localhost").GET("/host", func() string { return "host" })
+	// 3. 注册完整 Host
+	ws.Host("example.com:9000").GET("/full", func() string { return "full" })
+
+	rh := &RouteHandler{ws: ws}
+
+	tests := []struct {
+		requestHost string
+		path        string
+		expected    string
+		code        int
+	}{
+		{"localhost:8080", "/port", "port", http.StatusOK},
+		{"otherhost:8080", "/port", "port", http.StatusOK},
+		{"localhost:9999", "/host", "host", http.StatusOK},
+		{"example.com:9000", "/full", "full", http.StatusOK},
+		{"example.com:8080", "/port", "port", http.StatusOK},
+		{"localhost:8080", "/host", "host", http.StatusOK},
+	}
+
+	for _, tt := range tests {
+		req := httptest.NewRequest("GET", tt.path, nil)
+		req.Host = tt.requestHost
+		w := httptest.NewRecorder()
+		rh.ServeHTTP(w, req)
+
+		if w.Code != tt.code {
+			t.Errorf("Host [%s] Path [%s] expected code %d, got %d", tt.requestHost, tt.path, tt.code, w.Code)
+		}
+		if tt.code == http.StatusOK && w.Body.String() != tt.expected {
+			t.Errorf("Host [%s] Path [%s] expected body %s, got %s", tt.requestHost, tt.path, tt.expected, w.Body.String())
+		}
+	}
+}
--- a/server.go
+++ b/server.go
@ -23,7 +23,12 @@ import (
 	"time"
 )

-type webServer struct {
+type staticType struct {
+	path     string
+	rootPath *string
+}
+
+type WebServer struct {
 	Config      ServiceConfig
 	server      *http.Server
 	listener    net.Listener
@ -67,6 +72,7 @@ type webServer struct {
 	codeStatics       map[string]map[string]*string
 	fileStatics       map[string]map[string]*string
 	dynamicStatics    map[string]map[string]*string
+	hostStatics       map[string][]*staticType
 	staticsByHostLock sync.RWMutex

 	// 过滤器与拦截器
@ -99,13 +105,13 @@ type webServer struct {
 }

 // DefaultServer 全局单例服务实例
-var DefaultServer = newWebServer()
+var DefaultServer = NewWebServer()

 // Config 全局配置对象 (指向 DefaultServer.Config)
 var Config = &DefaultServer.Config

-func newWebServer() *webServer {
-	ws := &webServer{
+func NewWebServer() *WebServer {
+	ws := &WebServer{
 		webServices:           make(map[string]map[string]*webServiceType),
 		regexWebServices:      make(map[string][]*webServiceType),
 		webServicesList:       make([]*webServiceType, 0),
@ -124,6 +130,7 @@ func newWebServer() *webServer {
 		codeStatics:           make(map[string]map[string]*string),
 		fileStatics:           make(map[string]map[string]*string),
 		dynamicStatics:        make(map[string]map[string]*string),
+		hostStatics:           make(map[string][]*staticType),
 		webAuthCheckers:       make(map[int]func(int, *log.Logger, *string, map[string]any, *Request, *Response, *WebServiceOptions) (pass bool, object any)),
 		injectObjects:         make(map[reflect.Type]any),
 		injectFunctions:       make(map[reflect.Type]func() any),
@ -137,7 +144,7 @@ func SetDiscovererForTest(d *discover.Discoverer) {
 }

 // ApplyConfig 将 ServiceConfig 中的路由策略应用到内部的文件级策略中
-func (ws *webServer) ApplyConfig() {
+func (ws *WebServer) ApplyConfig() {
 	ws.hostPoliciesLock.Lock()
 	defer ws.hostPoliciesLock.Unlock()

@ -225,7 +232,7 @@ func (ws *webServer) ApplyConfig() {
 	ws.rebuildStaticsUnderLock("")
 }

-func (ws *webServer) rebuildProxiesUnderLock(host string) {
+func (ws *WebServer) rebuildProxiesUnderLock(host string) {
 	combined := make([]*proxyType, 0)
 	combined = append(combined, ws.codeProxies[host]...)
 	combined = append(combined, ws.fileProxies[host]...)
@ -237,7 +244,7 @@ func (ws *webServer) rebuildProxiesUnderLock(host string) {
 	ws.hostProxies[host] = combined
 }

-func (ws *webServer) rebuildRewritesUnderLock(host string) {
+func (ws *WebServer) rebuildRewritesUnderLock(host string) {
 	combined := make([]*rewriteType, 0)
 	combined = append(combined, ws.codeRewrites[host]...)
 	combined = append(combined, ws.fileRewrites[host]...)
@ -249,7 +256,7 @@ func (ws *webServer) rebuildRewritesUnderLock(host string) {
 	ws.hostRewrites[host] = combined
 }

-func (ws *webServer) rebuildStaticsUnderLock(host string) {
+func (ws *WebServer) rebuildStaticsUnderLock(host string) {
 	combined := make(map[string]*string)
 	for k, v := range ws.codeStatics[host] {
 		combined[k] = v
@ -266,10 +273,20 @@ func (ws *webServer) rebuildStaticsUnderLock(host string) {
 	} else {
 		ws.staticsByHost[host] = combined
 	}
+
+	// 构造有序的静态路由列表 (按路径长度降序排列，实现最长匹配)
+	sorted := make([]*staticType, 0, len(combined))
+	for k, v := range combined {
+		sorted = append(sorted, &staticType{path: k, rootPath: v})
+	}
+	sort.Slice(sorted, func(i, j int) bool {
+		return len(sorted[i].path) > len(sorted[j].path)
+	})
+	ws.hostStatics[host] = sorted
 }

 // Start 启动服务，实现 starter.Service 接口
-func (ws *webServer) Start(ctx context.Context, logger *log.Logger) error {
+func (ws *WebServer) Start(ctx context.Context, logger *log.Logger) error {
 	if logger == nil {
 		logger = log.DefaultLogger
 	}
@ -425,7 +442,7 @@ func (ws *webServer) Start(ctx context.Context, logger *log.Logger) error {
 }

 // Stop 停止服务，实现 starter.Service 接口
-func (ws *webServer) Stop(ctx context.Context) error {
+func (ws *WebServer) Stop(ctx context.Context) error {
 	ws.running = false

 	// 执行停机钩子 (反序)
@ -448,7 +465,7 @@ func (ws *webServer) Stop(ctx context.Context) error {
 }

 // Status 检查服务健康状态，实现 starter.Service 接口
-func (ws *webServer) Status() (string, error) {
+func (ws *WebServer) Status() (string, error) {
 	if ws.server == nil || !ws.running {
 		return "", fmt.Errorf("server is not running")
 	}
@ -456,7 +473,7 @@ func (ws *webServer) Status() (string, error) {
 }

 // Reload 实现配置重新加载，实现 starter.Reloader 接口
-func (ws *webServer) Reload() error {
+func (ws *WebServer) Reload() error {
 	logger := ws.logger
 	if logger == nil {
 		logger = log.DefaultLogger
@ -473,7 +490,7 @@ func (ws *webServer) Reload() error {

 // AsyncServer 兼容旧版异步服务实例
 type AsyncServer struct {
-	*webServer
+	*WebServer
 }

 // Stop 兼容旧版的无参数停止方法
@ -484,13 +501,13 @@ func (as *AsyncServer) Stop() {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), stopTimeout)
 	defer cancel()
-	_ = as.webServer.Stop(ctx)
+	_ = as.WebServer.Stop(ctx)
 }

 // AsyncStart 兼容旧版的异步启动方法
 func AsyncStart() *AsyncServer {
 	_ = DefaultServer.Start(context.Background(), log.DefaultLogger)
-	return &AsyncServer{webServer: DefaultServer}
+	return &AsyncServer{WebServer: DefaultServer}
 }

 // Wait 等待服务结束 (兼容旧版，直接阻塞)
@ -511,6 +528,8 @@ func Start() {
 			stopTimeout = 5 * time.Second
 		}
 		starter.Register("web-server", DefaultServer, 100, 5*time.Second, stopTimeout)
-		starter.Run()
+		if err := starter.Start(); err == nil {
+			starter.Wait()
+		}
 	})
 }
--- a/service.go
+++ b/service.go
@ -61,7 +61,7 @@ func SetClientKeys(deviceIdKey, clientAppKey, sessionIdKey string) {
 	DefaultServer.SetClientKeys(deviceIdKey, clientAppKey, sessionIdKey)
 }

-func (ws *webServer) SetClientKeys(deviceIdKey, clientAppKey, sessionIdKey string) {
+func (ws *WebServer) SetClientKeys(deviceIdKey, clientAppKey, sessionIdKey string) {
 	ws.usedDeviceIdKey = deviceIdKey
 	ws.usedClientAppKey = clientAppKey
 	ws.usedSessionIdKey = sessionIdKey
@ -72,7 +72,7 @@ func SetSessionIdMaker(maker func() string) {
 	DefaultServer.SetSessionIdMaker(maker)
 }

-func (ws *webServer) SetSessionIdMaker(maker func() string) {
+func (ws *WebServer) SetSessionIdMaker(maker func() string) {
 	ws.sessionIdMaker = maker
 }

@ -81,7 +81,7 @@ func SetAuthChecker(authChecker func(authLevel int, logger *log.Logger, url *str
 	DefaultServer.SetAuthChecker(authChecker)
 }

-func (ws *webServer) SetAuthChecker(authChecker func(authLevel int, logger *log.Logger, url *string, in map[string]any, request *Request, response *Response, options *WebServiceOptions) (pass bool, object any)) {
+func (ws *WebServer) SetAuthChecker(authChecker func(authLevel int, logger *log.Logger, url *string, in map[string]any, request *Request, response *Response, options *WebServiceOptions) (pass bool, object any)) {
 	ws.webAuthChecker = authChecker
 }

@ -90,7 +90,7 @@ func AddAuthChecker(authLevels []int, authChecker func(authLevel int, logger *lo
 	DefaultServer.AddAuthChecker(authLevels, authChecker)
 }

-func (ws *webServer) AddAuthChecker(authLevels []int, authChecker func(authLevel int, logger *log.Logger, url *string, in map[string]any, request *Request, response *Response, options *WebServiceOptions) (pass bool, object any)) {
+func (ws *WebServer) AddAuthChecker(authLevels []int, authChecker func(authLevel int, logger *log.Logger, url *string, in map[string]any, request *Request, response *Response, options *WebServiceOptions) (pass bool, object any)) {
 	for _, al := range authLevels {
 		ws.webAuthCheckers[al] = authChecker
 	}
@ -101,7 +101,7 @@ func SetInFilter(filter func(in *map[string]any, request *Request, response *Res
 	DefaultServer.SetInFilter(filter)
 }

-func (ws *webServer) SetInFilter(filter func(in *map[string]any, request *Request, response *Response, logger *log.Logger) (out any)) {
+func (ws *WebServer) SetInFilter(filter func(in *map[string]any, request *Request, response *Response, logger *log.Logger) (out any)) {
 	ws.inFilters = append(ws.inFilters, filter)
 }

@ -110,7 +110,7 @@ func AddShutdownHook(hook func()) {
 	DefaultServer.AddShutdownHook(hook)
 }

-func (ws *webServer) AddShutdownHook(hook func()) {
+func (ws *WebServer) AddShutdownHook(hook func()) {
 	ws.shutdownHooksLock.Lock()
 	defer ws.shutdownHooksLock.Unlock()
 	ws.shutdownHooks = append(ws.shutdownHooks, hook)
@ -121,7 +121,7 @@ func SetOutFilter(filter func(in map[string]any, request *Request, response *Res
 	DefaultServer.SetOutFilter(filter)
 }

-func (ws *webServer) SetOutFilter(filter func(in map[string]any, request *Request, response *Response, out any, logger *log.Logger) (newOut any, isOver bool)) {
+func (ws *WebServer) SetOutFilter(filter func(in map[string]any, request *Request, response *Response, out any, logger *log.Logger) (newOut any, isOver bool)) {
 	ws.webServicesLock.Lock()
 	defer ws.webServicesLock.Unlock()
 	ws.outFilters = append(ws.outFilters, filter)
@ -130,7 +130,7 @@ func (ws *webServer) SetOutFilter(filter func(in map[string]any, request *Reques

 // HostContext 提供流式服务注册能力
 type HostContext struct {
-	ws   *webServer
+	ws   *WebServer
 	host string
 }

@ -139,7 +139,7 @@ func Host(host string) *HostContext {
 	return DefaultServer.Host(host)
 }

-func (ws *webServer) Host(host string) *HostContext {
+func (ws *WebServer) Host(host string) *HostContext {
 	if host == "" {
 		host = "*"
 	}
@ -151,7 +151,7 @@ func Register(method, path string, serviceFunc any) *webServiceType {
 	return DefaultServer.Register(method, path, serviceFunc)
 }

-func (ws *webServer) Register(method, path string, serviceFunc any) *webServiceType {
+func (ws *WebServer) Register(method, path string, serviceFunc any) *webServiceType {
 	return ws.Host("*").Register(method, path, serviceFunc)
 }

@ -160,7 +160,7 @@ func RegisterWebsocket(path string, serviceFunc any) *websocketServiceType {
 	return DefaultServer.RegisterWebsocket(path, serviceFunc)
 }

-func (ws *webServer) RegisterWebsocket(path string, serviceFunc any) *websocketServiceType {
+func (ws *WebServer) RegisterWebsocket(path string, serviceFunc any) *websocketServiceType {
 	return ws.Host("*").WebSocket(path, serviceFunc)
 }

@ -169,7 +169,7 @@ func Proxy(authLevel int, path string, to string) {
 	DefaultServer.Proxy(authLevel, path, to)
 }

-func (ws *webServer) Proxy(authLevel int, path string, to string) {
+func (ws *WebServer) Proxy(authLevel int, path string, to string) {
 	ws.Host("*").Proxy(authLevel, path, to)
 }

@ -178,7 +178,7 @@ func Restful(authLevel int, path string, serviceStruct any) {
 	DefaultServer.Restful(authLevel, path, serviceStruct)
 }

-func (ws *webServer) Restful(authLevel int, path string, serviceStruct any) {
+func (ws *WebServer) Restful(authLevel int, path string, serviceStruct any) {
 	ws.Host("*").Restful(authLevel, path, serviceStruct)
 }

@ -468,7 +468,7 @@ func GetInject(dataType reflect.Type) any {
 	return DefaultServer.GetInject(dataType)
 }

-func (ws *webServer) GetInject(dataType reflect.Type) any {
+func (ws *WebServer) GetInject(dataType reflect.Type) any {
 	if obj, exists := ws.injectObjects[dataType]; exists {
 		return obj
 	}
@ -497,7 +497,7 @@ func EnableWebDev(config watch.Config) {
 	DefaultServer.webDevConfig = config
 }

-func (ws *webServer) initWebDev(logger *log.Logger) {
+func (ws *WebServer) initWebDev(logger *log.Logger) {
 	webDevOnce.Do(func() {
 		logger.Warning("Web Development Mode Enabled. This should NOT be used in production environment.")
 		onWatchConn := map[string]*WebSocketConn{}
--- a/static.go
+++ b/static.go
@ -5,6 +5,7 @@ import (
 	"apigo.cc/go/log"
 	"mime"
 	"net/http"
+	"net/url"
 	"path/filepath"
 	"strings"
 	"time"
@ -25,7 +26,7 @@ func Static(path, rootPath string) {
 	DefaultServer.Static(path, rootPath)
 }

-func (ws *webServer) Static(path, rootPath string) {
+func (ws *WebServer) Static(path, rootPath string) {
 	ws.Host("*").Static(path, rootPath)
 }

@ -34,7 +35,7 @@ func StaticByHost(path, rootPath, host string) {
 	DefaultServer.StaticByHost(path, rootPath, host)
 }

-func (ws *webServer) StaticByHost(path, rootPath, host string) {
+func (ws *WebServer) StaticByHost(path, rootPath, host string) {
 	if !filepath.IsAbs(rootPath) {
 		if absPath, err := filepath.Abs(rootPath); err == nil {
 			rootPath = absPath
@ -56,7 +57,7 @@ func ReplaceStatics(host string, config map[string]string) {
 	DefaultServer.ReplaceStatics(host, config)
 }

-func (ws *webServer) ReplaceStatics(host string, config map[string]string) {
+func (ws *WebServer) ReplaceStatics(host string, config map[string]string) {
 	newStatics := make(map[string]*string, len(config))
 	for path, rootPath := range config {
 		rp := rootPath
@ -75,31 +76,30 @@ func (ws *webServer) ReplaceStatics(host string, config map[string]string) {
 	ws.rebuildStaticsUnderLock(host)
 }

-func (ws *webServer) getStaticFilePath(requestPath, host string) string {
+func (ws *WebServer) getStaticFilePath(requestPath, host string) string {
+	requestPath, _ = url.PathUnescape(requestPath)
 	ws.staticsByHostLock.RLock()
 	defer ws.staticsByHostLock.RUnlock()

 	// 优先匹配指定域名的配置
-	if hostConfig, exists := ws.staticsByHost[host]; exists {
-		if filePath := ws.findMatchedPath(hostConfig, requestPath); filePath != "" {
+	if filePath := ws.findMatchedPathSorted(ws.hostStatics[host], requestPath); filePath != "" {
 		return filePath
 	}
-	}

 	// 匹配全局配置
-	return ws.findMatchedPath(ws.statics, requestPath)
+	return ws.findMatchedPathSorted(ws.hostStatics[""], requestPath)
 }

-func (ws *webServer) findMatchedPath(config map[string]*string, requestPath string) string {
-	for urlPath, rootPath := range config {
-		if strings.HasPrefix(requestPath, urlPath) {
-			return filepath.Join(*rootPath, requestPath[len(urlPath):])
+func (ws *WebServer) findMatchedPathSorted(config []*staticType, requestPath string) string {
+	for _, rule := range config {
+		if strings.HasPrefix(requestPath, rule.path) {
+			return filepath.Join(*rule.rootPath, requestPath[len(rule.path):])
 		}
 	}
 	return ""
 }

-func (ws *webServer) processStatic(requestPath string, request *Request, response *Response, logger *log.Logger) bool {
+func (ws *WebServer) processStatic(requestPath string, request *Request, response *Response, logger *log.Logger) bool {
 	filePath := ws.getStaticFilePath(requestPath, request.Host)
 	if filePath == "" {
 		return false
--- a/websocket.go
+++ b/websocket.go
@ -59,7 +59,7 @@ func Upgrade(response *Response, request *Request) (*WebSocketConn, error) {
 	return &WebSocketConn{Conn: conn}, nil
 }

-func (ws *webServer) doWebsocketService(wsc *websocketServiceType, request *Request, response *Response, logger *log.Logger, object any) {
+func (ws *WebServer) doWebsocketService(wsc *websocketServiceType, request *Request, response *Response, logger *log.Logger, object any) {
 	wsConn, err := Upgrade(response, request)
 	if err != nil {
 		logger.Error("websocket upgrade failed", "error", err.Error())
Author	SHA1	Message	Date
AI Engineer	038e14f3d8	feat: align JS exports to PascalCase (by AI)	2026-06-10 12:14:54 +08:00
AI Engineer	a7c08cdf26	refactor: align with starter v1.5.3 Start/Wait pattern	2026-06-08 00:20:13 +08:00
AI Engineer	c891d37fad	refactor(service): export WebServer and NewWebServer for compatibility	2026-06-06 09:35:02 +08:00
AI Engineer	fbf7e6475c	fix(service): enhance routing robustness and static file matching v1.5.11	2026-06-06 08:59:14 +08:00
AI Engineer	582de60053	fix: service.Static() URL decoding bug	2026-06-05 21:15:04 +08:00