Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

256 lines (219 sloc) 8.7 KB

后端开发手册

目录

背景:

  • 开发语言分为Java、Go、HTML5/Vue.js、Android、iOS;
  • 本次前后端通讯技术使用gRPC方案, 数据存储使用PostgreSQLRedis等方案;
  • 本手册默认/适用于开发者均熟悉以上技术.

PostgreSQL开发规范

命名规范

  • 数据库名: <数据库名>_db

  • 用户名: <用户名>_u

  • 表名: <模块名>_<业务名>

    • 以小写字母、下划线、数字组成;
    • 不要以pg开头
    • 不要以数字开头
    • 不要使用保留字
    • 不建议用复数, 比如action,而不是actions
      create table iam_user #iam:模块名, user:业务名
    
  • 关联关系表名/中间表表名: <模块名>_<业务名a>_<业务名b>_ref

    • 遵循表名命名规范
      create table iam_user_role_ref
    
  • 临时表名: 以 tmp_ 开头,表名以特定规则结尾

    • 遵循表名命名规范
      tmp_iam_user_2019
      tmp_product_a01,tmp_product_a02
    
  • 字段名/别名: 全部小写/lowercase

    • 字段名尽量用行业术语/专业术语的名词形式,比如:
      • 启用/停用,用enabled表示,它是专业术语的名词形式
      • 类型,用type表示
  • 索引名

    • 主键索引以 pk_ 开头
    • 唯一索引以 uk_ 开头
    • 普通索引以 idx_ 开头

设计规范

  • 各表统一添加如下字段:

      deleted boolean default false,
      createtime timestamp,
      createid varchar(32),
      createname varchar(64),
      updatetime timestamp,
      updateid varchar(32),
      updatename varchar(64),
      locked timestamp
    
  • 各表中同一含义的字段名,字段名数据类型 必须保持一致;

  • 各表中不以FOREIGN KEY关键字建立主外键关系,而是定义业务外键,比如表名id:

    create table iam_test  (  
      id varchar(32),
      <iamfkid> varchar(32) #表名:iam_fk,去掉_,iamfkid
      name varchar(64),  
    ); 
  • 所有字段设置非空约束not null,并设置默认值default

    • 特别是业务非首次执行的操作,比如修改人id、修改人、修改时间则设置为新增相关信息
    • 默认值
      • boolean
        • 0 false
        • 1 true
      • numeric
        • 0
      • string
        • ""
      • date
        • now()当前时间
  • JDBC Driver Using Java 8 Date and Time classes


gRPC接口开发规范

  • 接口定义依据proto3语法定义;

  • 接口定义风格将遵循proto3 style guide定义;

  • 扩展接口风格Message and field names, 请求/响应消息定义规则:

    Action Required Remark
    Login N 登入
    Logout N 注销
    Post N 新增
    Put N 修改
    Delete N 删除
    Get N 获取
    Request Y 请求
    Response Y 响应
    • ${Action} - ${Message} - <optional -s> - Request / Response ,比如
      • 账户登录: LoginRequest / LoginResponse
      • 账户注销: LogoutRequest / LogoutResponse
      • 新增用户: PostUserRequest / PostUserResponse
      • 获取单个用户: GetUserRequest / GetUserRequest
      • 获取多个用户: GetUsersRequest / GetUsersResponse
        service UserService {
          rpc PostUser (PostUserRequest) returns (PostUserResponse);
          rpc PutUser (PutUserRequest) returns (PutUserResponse);
          rpc DeleteUsers (DeleteUsersRequest) returns (DeleteUsersResponse);
          
        }
        message PostUserRequest{
          // 尽量只定义所有必填字段; [注意]: 公共/系统获取的字段为非必填字段
          string firstname=1;
          string lastname=2;
          string username=3;
        }
            
    
  • 注意,message-filed-name不以下划线拼接,比如:

      string firstname=1,不是string first_name=1
    
  • 接口状态码参考gRPC Status Codes定义;

    • 16/401: 帐号密码错误
    • 7/403: Token失效
    • 3/400: 参数错误
    • 9/400: 帐号处于停用状态/证书过期
    • 11/400: 资源权限不足
  • 接口安全参考gRPC Authentication实现;

  • 接口异常遵守gRPC ErrorHTTP2 Error定义;

  • 接口分为内部接口外部接口

    • 内部接口 Internal API,即服务间通讯的接口;

      • 默认服务彼此信任,安全;
    • 外部接口 External API,即对外暴露的接口;

      • 所有接口必须通过IAM服务认证;
      • 外部接口又分:
        • Web 根据实际情况可以再细分
        • App
        • All Web和App共用的接口, 比如登录, 部分Edge服务接口
    • 举例:

      • 工程目录
      /protobuf
        /protobuf-internal
          /iam
            iir-resource.proto
        /protobuf-web
          /iam
            iwp-policy.proto
            iwr-resource.proto
          /opm
            owc-customer.proto
        /protobuf-app
          /iam
            iap-policy.proto
            iar-resource.proto
        /protobuf-all
          /iam
            iai-identity.proto
      
      - ###transform protobuf to rpc-api by git subtree commands###
      
      /rpc-api
        /protobuf-internal
          /iam
            iir-resource.proto
        /protobuf-web
          /iam
            iwp-policy.proto
            iwr-resource.proto
          /opm
            owc-customer.proto
        /protobuf-app
          /iam
            iap-policy.proto
            iar-resource.proto
        /protobuf-all
          /iam
            iai-identity.proto
      
      • Proto文件
      iwr-resource.proto // iwr根据objc_class_prefix="IWR"
        syntax = "proto3";
        option java_multiple_files = true;
        option java_package="com.domain.iam.web.resource";  // tips 1
          #option java_package="com.domain.iam.app.resource";
          #option java_package="com.domain.iam.all.resource";
          #option java_package="com.domain.iam.internal.resource";
      
        option objc_class_prefix="IWR"; // iam.web.resource 可以取首字母;  // tips 2
        package iam.web.resource; // tips 3 取IWR的全写
        
        import "google/protobuf/empty.proto";
        
        service ResourceService {
            rpc GetResources (GetResourcesRequest) returns (GetResourcesResponse);
        }
        
        tips1,2,3: 注意修改包名, web, app, all, internal
      
      • Java目录
      src/main/java
        com/domain/iam/service #service包
        // Web的外部接口 extends com.domain.iam.web.resource.ResourceServiceImplBase
        ResourceForWebServiceImpl.java
        // App的外部接口 extends com.domain.iam.app.resource.ResourceServiceImplBase
        ResourceForAppServiceImpl.java 
        // Web和App的外部接口 extends com.domain.iam.all.identity.IdentityServiceImplBase
        IdentityForAllServiceImpl.java
        // 内部接口 extends com.domain.iam.internal.resource.ResourceRefServiceImplBase
        ResourceRefServiceImpl.java
      

数据字典规范

  • 确定的数据定义,比如全国区域信息定义、各个业务类型定义等,在各前端(Web,iOS,Android)维护;
    • 方法: 可以通过git的subtree或者配置中心(Java)统一维护;
  • 不确定的数据定义,需要定义数据库字典表,在Web后台维护;

结语

  • 该规范并没有严格遵守最佳实践,目的是在开发效率、可维护性、可读性等实践之间取得一个平衡:
  • 该规范会不断完善,如果大家有好的建议欢迎讨论,或者提交Issues.

You can’t perform that action at this time.