API с ограниченной областью действия и приёмы повышения читаемости

Зачем ограничивать область DSL?

Шаблон пространства имён

struct Route { let method: String; let path: String }

// Namespace instead of global free functions
enum R {
    static func GET(_ path: String) -> Route  { Route(method: "GET",  path: path) }
    static func POST(_ path: String) -> Route { Route(method: "POST", path: path) }
}

@resultBuilder
struct RoutesBuilder {
    static func buildBlock(_ parts: Route...) -> [Route] { parts }
}

func routes(@RoutesBuilder _ content: () -> [Route]) -> [Route] { content() }

let table = routes {
    R.GET("/home")
    R.POST("/upload")
}
for r in table { print("\(r.method) \(r.path)") }

Помощник для группировки

// Group routes by a shared prefix using a helper
func section(_ prefix: String, @RoutesBuilder _ content: () -> [Route]) -> [Route] {
    content().map { Route(method: $0.method, path: prefix + $0.path) }
}

let grouped = routes {
    R.GET("/health")
    section("/admin") {
        R.GET("/dashboard")
        R.POST("/upload")
    }
}
for r in grouped { print("\(r.method) \(r.path)") } // /admin/* prefixed

Разделяйте задачи

// A separate builder for middlewares (keeps concerns isolated)
struct Middleware { let name: String }

@resultBuilder
struct MiddlewareBuilder {
    static func buildBlock(_ parts: Middleware...) -> [Middleware] { parts }
}

enum M {
    static func log(_ name: String) -> Middleware { Middleware(name: "log:\(name)") }
    static func auth() -> Middleware { Middleware(name: "auth") }
}

func middlewares(@MiddlewareBuilder _ content: () -> [Middleware]) -> [Middleware] { content() }

let mw = middlewares {
    M.log("requests")
    M.auth()
}
print(mw.map(\.name))

Советы по читаемости

Помощник для проверки

// Add a simple validator to catch mistakes early
func validate(_ routes: [Route]) -> [String] {
    var issues: [String] = []
    let seen = Set(routes.map { $0.method + " " + $0.path })
    if seen.count != routes.count { issues.append("Duplicate route detected") }
    if routes.contains(where: { !$0.path.hasPrefix("/") }) {
        issues.append("Paths must start with /")
    }
    return issues
}

let issues = validate(grouped)
print(issues.isEmpty ? "OK" : "Issues: \(issues)")

Шаблон ограниченного программного интерфейса

Итоги