Backend API & Protobuf Definitions

The GoWind Admin backend follows a Protobuf First API development model: all endpoints are defined in Protobuf, and the Buf toolchain automatically generates the Go server code, TypeScript client code, and OpenAPI documentation.

1. Protobuf Organization

All Protobuf definition files are located under the backend/api/protos/ directory, organized by business domain:

api/protos/
├── admin/service/v1/       # Admin service interface definitions (HTTP routes, request/response messages)
├── audit/                  # Audit log message definitions
├── authentication/         # Authentication message definitions
├── dict/                   # Dictionary management message definitions
├── identity/               # Identity management message definitions (user, role, org, tenant, etc.)
├── internal_message/       # Internal message definitions
├── permission/             # Permission management message definitions
├── storage/                # File storage message definitions
└── task/                   # Task scheduling message definitions

Module Descriptions

2. Service Definition Conventions

Using the authentication service as an example of a standard Service definition:

syntax = "proto3";

package admin.service.v1;

import "gnostic/openapi/v3/annotations.proto";
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "authentication/service/v1/authentication.proto";

// Backend login authentication service
service AuthenticationService {
  // Login
  rpc Login (authentication.service.v1.LoginRequest) returns (authentication.service.v1.LoginResponse) {
    option (google.api.http) = {
      post: "/admin/v1/login"
      body: "*"
    };
    option(gnostic.openapi.v3.operation) = {
      security: {}
    };
  }

  // Logout
  rpc Logout (google.protobuf.Empty) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/admin/v1/logout"
      body: "*"
    };
  }
}

Key Conventions

1. HTTP route mapping: the HTTP method and path are specified via the google.api.http annotation
2. Unified prefix: all Admin API routes are prefixed with /admin/v1/
3. OpenAPI security annotation: endpoints that require no authentication are annotated with security: {} (e.g. login, captcha)
4. Package naming: admin.service.v1 is used for Service definitions; other messages are packaged by domain

3. API Endpoint List

1. Authentication Service (AuthenticationService)

2. User Management Service

3. Tenant Management Service

4. Role Management Service

5. Permission Management Service

6. Menu Management Service

7. Organization Management Service

8. Dictionary Management Service

9. File Management Service

10. Internal Message Service

11. Task Scheduling Service

12. Dashboard Service (AdminPortalService)

13. Audit Log Service

4. Code Generation

1. Buf Configuration

Buf configuration files are located in the api/ directory:

2. Generation Commands

# Generate Go server code (HTTP handlers, message types, error codes)
make api

# Generate OpenAPI v3 documentation
make openapi

# Generate TypeScript client code (Vue Vben + Vue Element + React)
make ts

# Generate everything in one go (Ent + Wire + API + OpenAPI)
make gen

3. Generated Code Output

api/gen/go/              # Go code
├── admin/service/v1/    # Admin service generated code (HTTP handlers, interface definitions)
├── audit/service/v1/    # Audit service generated code
├── authentication/      # Authentication message code
├── dict/                # Dictionary message code
├── identity/            # Identity message code
├── internal_message/    # Internal message code
├── permission/          # Permission message code
├── storage/             # Storage message code
└── task/                # Task message code

5. Swagger UI

Swagger UI is enabled by default in the development environment, accessible at: http://localhost:7788/docs/

Swagger UI is integrated via kratos-swagger-ui and registered in rest_server.go:

if cfg.GetServer().GetRest().GetEnableSwagger() {
    swaggerUI.RegisterSwaggerUIServerWithOption(
        srv,
        swaggerUI.WithTitle("GoWind Admin"),
        swaggerUI.WithMemoryData(assets.OpenApiData, "yaml"),
    )
}

OpenAPI documentation URLs:

• Swagger UI: http://localhost:7788/docs/
• OpenAPI YAML: http://localhost:7788/docs/openapi.yaml

6. Error Code Definitions

Error codes are defined in Protobuf and automatically generate Go error types. The error code definition file is admin_error.proto:

enum ErrorReason {
  option (errors.default_code) = 500;

  INTERNAL_SERVER_ERROR = 0;
  INVALID_GRANT_TYPE = 1;
  INCORRECT_REFRESH_TOKEN = 2;
  FORBIDDEN = 3;
  // ...
}

The generated error types support HTTP status code mapping and can be used directly in the Service layer:

return nil, authenticationV1.ErrorInvalidGrantType("invalid grant type")

7. Adding a New API

Step 1: Define the Protobuf

Create or modify a .proto file under the corresponding directory in api/protos/:

syntax = "proto3";
package admin.service.v1;

import "google/api/annotations.proto";

service MyNewService {
  rpc GetMyData (GetMyDataRequest) returns (GetMyDataResponse) {
    option (google.api.http) = {
      get: "/admin/v1/my-data"
    };
  }
}

message GetMyDataRequest {
  uint32 id = 1;
}

message GetMyDataResponse {
  string name = 1;
}

Step 2: Generate the Code

make api

Step 3: Implement the Service

Create my_new_service.go under internal/service/, implementing the generated interface.

Step 4: Register with the Server

Register the new Service Handler in internal/server/rest_server.go.

Step 5: Regenerate Wire

cd app/admin/service/cmd/server
wire

8. Related Documents

• Backend Architecture Overview
• Backend Core Modules in Depth
• Backend Configuration & Deployment